coconet-python 0.4.4__py3-none-any.whl

coconet/__init__.py

@@ -0,0 +1,13 @@
+"""CoCoNet headless model package."""
+
+from coconet.api import CoconetRunResult, load_coconet_config, run_coconet
+from coconet.config import CoconetConfig
+from coconet.model import CoconetModel
+
+__all__ = [
+    "CoconetConfig",
+    "CoconetModel",
+    "CoconetRunResult",
+    "load_coconet_config",
+    "run_coconet",
+]

coconet/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m coconet`` as an alternative to the ``coconet`` console script."""
+
+from coconet.cli import main
+
+if __name__ == "__main__":
+    main()

coconet/api.py

@@ -0,0 +1,110 @@
+"""Stable library entry points for running CoCoNet outside the bundled CLI.
+
+Other clients (custom CLIs, orchestration, containers) should prefer this module:
+load configuration via :func:`load_coconet_config`, then execute with
+:func:`run_coconet`.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from pathlib import Path
+from typing import Any
+
+from coconet.config import CoconetConfig
+from coconet.logging_utils import configure_logging
+from coconet.model import CoconetModel
+
+__all__ = [
+    "CoconetRunResult",
+    "load_coconet_config",
+    "run_coconet",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def _config_field_names() -> frozenset[str]:
+    return frozenset(f.name for f in fields(CoconetConfig))
+
+
+def _apply_mapping_overrides(config: CoconetConfig, values: Mapping[str, Any]) -> None:
+    valid = _config_field_names()
+    for key, value in values.items():
+        if key not in valid:
+            raise TypeError(f"Unknown CoconetConfig attribute: {key!r}")
+        setattr(config, key, value)
+
+
+@dataclass(slots=True)
+class CoconetRunResult:
+    """Outcome of :func:`run_coconet` (extend with metrics later if needed)."""
+
+    output_file: str
+
+
+def load_coconet_config(
+    *,
+    config_file: str | Path | None = None,
+    parameter_file: str | Path | None = None,
+    env_prefix: str = "COCONET_",
+    scenario: Mapping[str, Any] | None = None,
+    **overrides: Any,
+) -> CoconetConfig:
+    """Build a :class:`~coconet.config.CoconetConfig` from files, env, and overrides.
+
+    Resolution order:
+
+    1. Defaults from :class:`~coconet.config.CoconetConfig`.
+    2. Optional YAML ``config_file`` (same keys as the dataclass fields).
+    3. Optional legacy NetLogo CSV ``parameter_file``.
+    4. Environment variables ``{env_prefix}FIELD`` (see :meth:`CoconetConfig.from_file`).
+    5. ``scenario`` mapping (flat dict of dataclass fields).
+    6. Keyword ``overrides`` (same names as dataclass fields); ``None`` values are skipped.
+
+    Unknown keys in ``scenario`` or ``overrides`` raise ``TypeError``.
+    """
+    cfg = CoconetConfig.from_file(
+        config_file=config_file,
+        parameter_file=parameter_file,
+        env_prefix=env_prefix,
+    )
+    if scenario is not None:
+        _apply_mapping_overrides(cfg, scenario)
+    for key, value in overrides.items():
+        if value is None:
+            continue
+        _apply_mapping_overrides(cfg, {key: value})
+    return cfg
+
+
+def run_coconet(
+    config: CoconetConfig,
+    *,
+    configure_logs: bool = False,
+    log_level: str | None = None,
+) -> CoconetRunResult:
+    """Run the simulation for ``config`` and return basic result metadata.
+
+    ``configure_logs``: when true, call :func:`~coconet.logging_utils.configure_logging`
+    using ``log_level`` if set, otherwise ``config.log_level``.
+
+    Idiomatic logging for library embedders: set ``configure_logs=False`` and configure
+    the standard logging module (or your framework's logging) yourself before calling.
+    """
+    if configure_logs:
+        level = log_level if log_level is not None else config.log_level
+        configure_logging(level)
+
+    logger.debug(
+        "CoCoNet run starting: reefs_file=%s coastline_file=%s output_file=%s",
+        config.reefs_file,
+        config.coastline_file,
+        config.output_file,
+    )
+    model = CoconetModel(config)
+    model.run()
+    logger.debug("CoCoNet run finished: output_file=%s", config.output_file)
+    return CoconetRunResult(output_file=config.output_file)

coconet/cli.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from coconet.api import load_coconet_config, run_coconet
+from coconet.logging_utils import configure_logging
+
+if TYPE_CHECKING:
+    from pyinstrument import Profiler
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run headless CoCoNet model.")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help="Optional YAML config file with scenario parameters.",
+    )
+    parser.add_argument(
+        "--parameter-file",
+        type=Path,
+        default=None,
+        help="Legacy NetLogo-style parameter CSV file.",
+    )
+    parser.add_argument(
+        "--output-file",
+        type=Path,
+        default=None,
+        help="Output CSV file path.",
+    )
+    parser.add_argument(
+        "--reefs-file",
+        type=Path,
+        default=None,
+        help="Reef attribute / spatial input CSV. Overrides config and COCONET_REEFS_FILE.",
+    )
+    parser.add_argument(
+        "--coastline-file",
+        type=Path,
+        default=None,
+        help="Coastline input CSV. Overrides config and COCONET_COASTLINE_FILE.",
+    )
+    parser.add_argument(
+        "--log-level",
+        type=str,
+        default=None,
+        help="Logging level (CRITICAL, ERROR, WARNING, INFO, DEBUG).",
+    )
+    parser.add_argument(
+        "--ensemble-threads",
+        type=int,
+        default=None,
+        metavar="N",
+        help="After ensemble-0 spinup, run simulation ensembles in parallel worker "
+        "processes (spawn): 1 = serial on the main process; 0 = auto "
+        "(min(CPU count, ensemble count)); N > 1 caps workers. "
+        "Default from config / COCONET_ENSEMBLE_THREADS.",
+    )
+    prof = parser.add_argument_group(
+        "profiling",
+        "Optional CPU profiling via pyinstrument (install: uv sync --extra profile).",
+    )
+    prof.add_argument(
+        "--profile",
+        action="store_true",
+        help="Profile the model run and write a dump to --profile-output.",
+    )
+    prof.add_argument(
+        "--profile-format",
+        choices=("html", "text", "speedscope"),
+        default="html",
+        help="Dump format: html (self-contained viewer), text (call tree), "
+        "or speedscope (open at https://www.speedscope.app/). Default: html.",
+    )
+    prof.add_argument(
+        "--profile-output",
+        type=Path,
+        default=None,
+        help="Output file path. Default: coconet-profile.<html|txt|speedscope.json>.",
+    )
+    prof.add_argument(
+        "--profile-interval",
+        type=float,
+        default=0.01,
+        metavar="SECONDS",
+        help="Seconds between CPU stack samples (pyinstrument default upstream is 0.001). "
+        "Coarser sampling (e.g. 0.01) keeps sessions smaller so the HTML report often "
+        "avoids heavy resampling. Use 0.001 for maximum detail.",
+    )
+    prof.add_argument(
+        "--profile-html-resample-interval",
+        type=float,
+        default=None,
+        metavar="SECONDS",
+        help="When using HTML output, optional resample_interval for pyinstrument's "
+        "HTMLRenderer (minimum time between retained samples in the viewer).",
+    )
+    return parser
+
+
+def _default_profile_path(fmt: str) -> Path:
+    if fmt == "html":
+        return Path("coconet-profile.html")
+    if fmt == "text":
+        return Path("coconet-profile.txt")
+    return Path("coconet-profile.speedscope.json")
+
+
+def _write_profile_dump(
+    profiler: Profiler,
+    path: Path,
+    fmt: str,
+    *,
+    html_resample_interval: float | None,
+    logger: logging.Logger,
+) -> None:
+    if fmt == "html":
+        session = profiler.last_session
+        n_samples = len(session.frame_records) if session is not None else 0
+        if n_samples > 100_000:
+            logger.info(
+                "Profile HTML: session has %s stack samples; the interactive viewer "
+                "uses resampled data (pyinstrument limit ~100k). "
+                "Use a larger --profile-interval and/or --profile-format speedscope "
+                "for long runs.",
+                n_samples,
+            )
+        # pyinstrument always prints a noisy resample notice to stderr when
+        # resampling; we already log above and pass resample_interval when set.
+        stderr_buf = io.StringIO()
+        with contextlib.redirect_stderr(stderr_buf):
+            content = profiler.output_html(resample_interval=html_resample_interval)
+        extra = stderr_buf.getvalue().strip()
+        if extra:
+            logger.debug("%s", extra)
+    elif fmt == "text":
+        content = profiler.output_text(unicode=True, color=False)
+    else:
+        from pyinstrument.renderers import SpeedscopeRenderer
+
+        content = profiler.output(SpeedscopeRenderer())
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    bootstrap_level = args.log_level or os.getenv("COCONET_LOG_LEVEL") or "INFO"
+    try:
+        configure_logging(bootstrap_level)
+    except ValueError as exc:
+        parser.error(str(exc))
+        return
+
+    logger = logging.getLogger(__name__)
+    logger.debug(
+        "Loading configuration (config_file=%s, parameter_file=%s).",
+        args.config,
+        args.parameter_file,
+    )
+
+    cli_overrides: dict[str, Any] = {}
+    if args.output_file is not None:
+        cli_overrides["output_file"] = str(args.output_file)
+    if args.reefs_file is not None:
+        cli_overrides["reefs_file"] = str(args.reefs_file)
+    if args.coastline_file is not None:
+        cli_overrides["coastline_file"] = str(args.coastline_file)
+    if args.log_level is not None:
+        cli_overrides["log_level"] = args.log_level
+    if args.ensemble_threads is not None:
+        cli_overrides["ensemble_threads"] = args.ensemble_threads
+
+    config = load_coconet_config(
+        config_file=args.config,
+        parameter_file=args.parameter_file,
+        **cli_overrides,
+    )
+
+    try:
+        effective_log_level = configure_logging(config.log_level)
+    except ValueError as exc:
+        parser.error(str(exc))
+        return
+
+    logger = logging.getLogger(__name__)
+    logger.info(
+        "Starting CoCoNet run: log_level=%s reefs_file=%s coastline_file=%s "
+        "output_file=%s config_file=%s parameter_file=%s",
+        effective_log_level,
+        config.reefs_file,
+        config.coastline_file,
+        config.output_file,
+        args.config,
+        args.parameter_file,
+    )
+
+    if args.profile:
+        try:
+            from pyinstrument import Profiler
+        except ImportError:
+            parser.error(
+                "Profiling needs pyinstrument. Install the optional extra, e.g. "
+                "`uv sync --extra profile` or `pip install 'coconet-python[profile]'`."
+            )
+        if args.profile_interval <= 0:
+            parser.error("--profile-interval must be positive.")
+        if (
+            args.profile_html_resample_interval is not None
+            and args.profile_html_resample_interval < 0
+        ):
+            parser.error(
+                "--profile-html-resample-interval must be non-negative "
+                "(0 disables HTML resampling)."
+            )
+        out = args.profile_output or _default_profile_path(args.profile_format)
+        profiler = Profiler(interval=args.profile_interval)
+        profiler.start()
+        try:
+            run_coconet(config, configure_logs=False)
+        finally:
+            profiler.stop()
+            _write_profile_dump(
+                profiler,
+                out,
+                args.profile_format,
+                html_resample_interval=args.profile_html_resample_interval,
+                logger=logger,
+            )
+        logger.info(
+            "Wrote %s profile to %s",
+            args.profile_format,
+            out.resolve(),
+        )
+    else:
+        run_coconet(config, configure_logs=False)
+
+    logger.info("CoCoNet run finished successfully.")
+
+
+if __name__ == "__main__":
+    main()

coconet/config.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import csv
+import os
+from dataclasses import dataclass, fields
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def effective_ensemble_workers(ensemble_threads: int, ensemble_runs: int) -> int:
+    """Cap for parallel simulation worker processes (ensembles 1..ensemble_runs).
+
+    ensemble_threads: 0 = auto (min(CPU count, simulation ensembles)), 1 = serial,
+    N > 1 = use at most N workers (still capped by ensemble_runs).
+    """
+    sim = max(0, ensemble_runs)
+    if sim == 0:
+        return 1
+    if ensemble_threads <= 0:
+        cap = os.cpu_count() or 1
+        return max(1, min(cap, sim))
+    return max(1, min(int(ensemble_threads), sim))
+
+
+def use_parallel_ensemble_run(ensemble_threads: int, ensemble_runs: int) -> bool:
+    return ensemble_runs > 0 and effective_ensemble_workers(ensemble_threads, ensemble_runs) > 1
+
+
+def _parse_scalar(text: str) -> Any:
+    value = text.strip()
+    if value == "":
+        return ""
+    lowered = value.lower()
+    if lowered in {"true", "false"}:
+        return lowered == "true"
+    try:
+        if "." in value or "e" in lowered:
+            number = float(value)
+            if number.is_integer():
+                return int(number)
+            return number
+        return int(value)
+    except ValueError:
+        return value
+
+
+@dataclass(slots=True)
+class CoconetConfig:
+    # Input/output
+    reefs_file: str = "legacy/reefs2024.csv"
+    coastline_file: str = "legacy/coastline.csv"
+    output_file: str = "output.csv"
+    parameter_file: str | None = None
+    log_level: str = "INFO"
+    # 0 = auto (min(CPU cores, simulation ensemble count)); 1 = serial; N > 1 = process pool cap.
+    ensemble_threads: int = 0
+
+    # Scenario controls (matching NetLogo globals)
+    SSP: float = 2.6
+    ensemble_runs: int = 20
+    start_year: int = 1956
+    # Years before start_year where ensemble-0 spinup begins (legacy NetLogo: 50).
+    spinup_backtrack_years: int = 50
+    save_year: int = 1986
+    projection_year: int = 2025
+    search_year: int = 9999
+    end_year: int = 2030
+
+    start_catchment_restore: int = 9999
+    restore_timeframe: float = 0.0
+
+    start_CoTS_control: int = 9999
+    eco_threshold: float = 8.0
+    CoTS_threshold: float = 999999.0
+    coral_threshold: float = 0.0
+    CoTS_vessels_GBR: int = 0
+    CoTS_vessels_FN: int = 0
+    CoTS_vessels_N: int = 0
+    CoTS_vessels_C: int = 0
+    CoTS_vessels_S: int = 0
+    CoTS_vessels_sector: int = 0
+
+    intervene_lon_min: float = 140.0
+    intervene_lon_max: float = 155.0
+    intervene_lat_min: float = -25.0
+    intervene_lat_max: float = -9.0
+
+    start_modified_zoning: int = 9999
+    rezoned_reefs: int = 0
+    start_modified_fishing: int = 9999
+    catch_reduction: float = 0.0
+    start_lower_sizelimit: int = 9999
+    start_upper_sizelimit: int = 9999
+    start_CoTSlimit: int = 9999
+
+    start_emperor_release: int = 9999
+    release_reefs: int = 500
+    release_threshold: float = 9999999.0
+    release_number: float = 0.0
+
+    start_regional_shading: int = 9999
+    regional_shading_reduction: float = 0.0
+    start_rubble_consolidation: int = 9999
+    consolidation_reefs: int = 0
+    consolidation_threshold: float = 0.0
+    consolidation_hectares: float = 0.0
+
+    start_coral_seeding: int = 9999
+    seed_reefs: int = 0
+    seed_threshold: float = 0.0
+    seed_hectares: float = 0.0
+    hybrid_fraction: float = 0.0
+    dominance: float = 0.0
+
+    start_coral_slick: int = 9999
+    slick_reefs: int = 0
+    slick_threshold: float = 0.0
+    slick_hectares: float = 0.0
+
+    start_reef_shading: int = 9999
+    shading_reefs: int = 0
+    reef_shading_reduction: float = 0.0
+    start_pH_protection: int = 9999
+    pH_reefs: int = 0
+    pH_protection: float = 0.0
+
+    # Legacy interface-only globals
+    search_mode: int = 0
+    perfect_intervention: str = ""
+    unregulated_fishing: bool = False
+
+    @classmethod
+    def from_file(
+        cls,
+        config_file: str | Path | None = None,
+        parameter_file: str | Path | None = None,
+        env_prefix: str = "COCONET_",
+    ) -> CoconetConfig:
+        config = cls()
+
+        if config_file is not None:
+            loaded = yaml.safe_load(Path(config_file).read_text()) or {}
+            for k, v in loaded.items():
+                if hasattr(config, k):
+                    setattr(config, k, v)
+
+        if parameter_file is not None:
+            config.parameter_file = str(parameter_file)
+            config._apply_legacy_parameter_file(Path(parameter_file))
+
+        config._apply_env_overrides(env_prefix)
+        return config
+
+    def _apply_env_overrides(self, env_prefix: str) -> None:
+        field_lookup = {f.name.lower(): f.name for f in fields(self)}
+        for env_key, env_value in os.environ.items():
+            if not env_key.startswith(env_prefix):
+                continue
+            key = env_key[len(env_prefix) :].lower()
+            if key not in field_lookup:
+                continue
+            attr = field_lookup[key]
+            setattr(self, attr, _parse_scalar(env_value))
+
+    def _apply_legacy_parameter_file(self, path: Path) -> None:
+        label_to_attr = {
+            "climate scenario": "SSP",
+            "ensemble runs": "ensemble_runs",
+            "start year": "start_year",
+            "spinup backtrack (years)": "spinup_backtrack_years",
+            "save year": "save_year",
+            "projection year": "projection_year",
+            "search year": "search_year",
+            "end year": "end_year",
+            "cots control start year": "start_CoTS_control",
+            "cots control ecological threshold (cots per ha)": "eco_threshold",
+            "cots control cots threshold (cots per ha)": "CoTS_threshold",
+            "cots control coral threshold (cots per ha)": "coral_threshold",
+            "cots vessels across gbr": "CoTS_vessels_GBR",
+            "cots vessels in far-northern region": "CoTS_vessels_FN",
+            "cots vessels in northern region": "CoTS_vessels_N",
+            "cots vessels in central region": "CoTS_vessels_C",
+            "cots vessels in southern region": "CoTS_vessels_S",
+            "catchment restoration start year": "start_catchment_restore",
+            "catchment restoration timescale (years)": "restore_timeframe",
+            "future zoning start year": "start_modified_zoning",
+            "number of reefs included in future rezoning": "rezoned_reefs",
+            "reduction in fisheries catch start year": "start_modified_fishing",
+            "fractional reduction in fisheries catches": "catch_reduction",
+            "upper fish size limit start year": "start_upper_sizelimit",
+            "lower fish size limit start year": "start_lower_sizelimit",
+            "exclude fishing from active outbreak reefs start year": "start_CoTSlimit",
+            "emperor release start year": "start_emperor_release",
+            "number of release reefs": "release_reefs",
+            "maximum adult emperors (per ha) for release": "release_threshold",
+            "number of juvenile emperors released per reef": "release_number",
+            "regional shading start year": "start_regional_shading",
+            "absolute dhw reduction due to regional shading (dhw)": "regional_shading_reduction",
+            "minimum longitude of interventions": "intervene_lon_min",
+            "maximum longitude of interventions": "intervene_lon_max",
+            "minimum latitude of interventions": "intervene_lat_min",
+            "maximum latitude of interventions": "intervene_lat_max",
+            "rubble consolidation start year": "start_rubble_consolidation",
+            "annual number of consolidated reefs": "consolidation_reefs",
+            "minimum rubble cover threshold for consolidation [0 1]": "consolidation_threshold",
+            "total annual consolidated area (ha)": "consolidation_hectares",
+            "thermally tolerant coral seeding start year": "start_coral_seeding",
+            "annual number of reefs seeded with coral": "seed_reefs",
+            "maximum coral cover threshold for coral seeding [0 1]": "seed_threshold",
+            "total annual area of seeded corals (ha)": "seed_hectares",
+            "fraction of staghorn acropora corals able to hybridise with thermally tolerant corals [0 1]": "hybrid_fraction",
+            "dominance of thermally tolerant corals in setting thermal tolerance of hybrids [0 1]": "dominance",
+            "coral slicks start year": "start_coral_slick",
+            "annual number of reefs with coral slicks released": "slick_reefs",
+            "maximum coral cover threshold for coral slicks [0 1]": "slick_threshold",
+            "total annual area of slick corals (ha)": "slick_hectares",
+            "reef shading start year": "start_reef_shading",
+            "annual number of reefs locally shaded": "shading_reefs",
+            "fractional dhw reduction due to local shading [0 1]": "reef_shading_reduction",
+            "ocean acidification treatment start year": "start_pH_protection",
+            "annual number of reefs treated for ocean acidification": "pH_reefs",
+            "fractional protection from ocean acidification [0 1]": "pH_protection",
+            "cots vessels in active sector": "CoTS_vessels_sector",
+        }
+
+        with path.open("r", newline="") as f:
+            reader = csv.reader(f)
+            for row in reader:
+                if len(row) < 2:
+                    continue
+                label = row[0].strip().lower()
+                # Header row "ensemble" marks end of config lines (not e.g. "ensemble runs").
+                if label.startswith("ensemble") and label == "ensemble":
+                    break
+                attr = label_to_attr.get(label)
+                if attr is None:
+                    continue
+                setattr(self, attr, _parse_scalar(row[1]))

coconet/logging_utils.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import logging
+
+VALID_LOG_LEVELS = ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG")
+
+
+def normalize_log_level(level: str | None) -> str:
+    if level is None:
+        return "INFO"
+    normalized = level.strip().upper()
+    if normalized not in VALID_LOG_LEVELS:
+        valid_levels = ", ".join(VALID_LOG_LEVELS)
+        raise ValueError(f"Invalid log level '{level}'. Valid levels: {valid_levels}.")
+    return normalized
+
+
+def configure_logging(level: str | None) -> str:
+    normalized_level = normalize_log_level(level)
+    logging.basicConfig(
+        level=getattr(logging, normalized_level),
+        format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        force=True,
+    )
+    return normalized_level