Network

@dataclass(frozen=True)
class Network:
    """A detector network: a named, ordered collection of detector specs.

    Attributes:
        name: Human-readable label for the network.
        detector_names: Ordered tuple of LAL detector prefix strings (e.g.
            ``"H1"``) or
            :class:`~gwmock_signal.detector.CustomDetector` instances.
    """

    name: str
    detector_names: tuple[str | CustomDetector, ...]

    # ------------------------------------------------------------------
    # Constructors
    # ------------------------------------------------------------------

    @classmethod
    def from_detectors(
        cls,
        detectors: Sequence[str | CustomDetector],
        *,
        name: str = "",
    ) -> Network:
        """Construct a :class:`Network` from any sequence of detector specs.

        String entries are validated against LAL's runtime detector list
        (``lal.cached_detector_by_prefix``), so any detector code that the
        installed LAL bindings know about works here without hard-coding.
        :class:`~gwmock_signal.detector.CustomDetector` instances are accepted
        as-is for non-standard geometries.

        Args:
            detectors: Sequence of LAL detector code strings (e.g. ``"H1"``)
                or :class:`~gwmock_signal.detector.CustomDetector` instances.
            name: Optional human-readable label.  Defaults to the
                comma-joined detector names.

        Returns:
            A :class:`Network` containing exactly the specified detectors.

        Raises:
            ValueError: If any string entry is not in LAL's available
                detector set, or if *detectors* is empty.
        """
        from gwmock_signal.detector import CustomDetector  # noqa: PLC0415

        if not detectors:
            raise ValueError("detectors must be a non-empty sequence.")

        lal_codes: set[str] = set(list_lal_detectors())
        validated: list[str | CustomDetector] = []
        for det in detectors:
            if isinstance(det, CustomDetector):
                validated.append(det)
            else:
                code = str(det)
                if code not in lal_codes:
                    raise ValueError(
                        f"Unknown LAL detector code {code!r}. "
                        f"Run Network.list_lal_detectors() to see available codes, "
                        "or use a CustomDetector for non-standard geometries."
                    )
                validated.append(code)

        auto_name = name or ",".join(d if isinstance(d, str) else d.name for d in validated)
        return cls(name=auto_name, detector_names=tuple(validated))

    @classmethod
    def from_name(cls, alias: str) -> Network:
        """Construct a :class:`Network` from a named preset.

        Args:
            alias: One of the pre-defined network names returned by
                :meth:`list_names`.

        Returns:
            A :class:`Network` whose ``detector_names`` are the detector codes
            for that preset.

        Raises:
            ValueError: If *alias* is not in the named presets.
        """
        if alias in _NETWORK_PRESETS:
            return cls(name=alias, detector_names=_NETWORK_PRESETS[alias])
        if alias in _FILE_BACKED_PRESET_ALIASES:
            return cls.from_preset(alias)
        raise ValueError(f"Unknown network {alias!r}. Known networks: {cls.list_names()}")

    @classmethod
    def from_preset(cls, alias: str) -> Network:
        """Construct a :class:`Network` from a bundled YAML/JSON detector preset.

        Bundled presets live under ``gwmock_signal.data.detectors`` and are
        resolved with :mod:`importlib.resources`, so they work from source trees
        and installed wheels alike.

        Args:
            alias: One of the bundled preset aliases returned by
                :meth:`list_names`, for example ``"ET-Triangle-Sardinia"``.

        Returns:
            A :class:`Network` loaded from the packaged detector geometry file.

        Raises:
            ValueError: If *alias* does not map to a bundled preset file.
            FileNotFoundError: If the mapped packaged preset file is missing.
        """
        resource = _preset_resource(alias)
        if not resource.is_file():
            raise FileNotFoundError(f"Bundled detector preset for {alias!r} is missing.")
        with as_file(resource) as path:
            net = cls.from_file(path)
        return cls.from_detectors(net.detector_names, name=net.name)

    @classmethod
    def from_file(cls, path: str | Path) -> Network:
        """Load a :class:`Network` from a YAML, JSON, or deprecated ``.interferometer`` file.

        The file must have a top-level ``name`` key (str) and a ``detectors``
        key containing a non-empty list of detector entries.  Each entry must
        have a ``name`` field. If any geometry key is present a
        :class:`~gwmock_signal.detector.CustomDetector` is constructed;
        otherwise the name is treated as a plain LAL detector code string.

        ``.interferometer`` files are treated as Bilby compatibility shims for
        a single custom detector and emit a :class:`DeprecationWarning`. Migrate
        those files to the YAML detector preset/network format instead.

        **Angle conventions** — every angle parameter accepts either a degrees
        variant (``*_deg``) or a radians variant (``*_rad``), but *not both* for
        the same parameter:

        +-----------------------+-------------------+-----------+
        | Parameter             | Degrees key       | Radians key |
        +=======================+===================+=============+
        | Geodetic latitude     | ``latitude_deg``  | ``latitude_rad`` |
        | Geodetic longitude    | ``longitude_deg`` | ``longitude_rad`` |
        | x-arm azimuth         | ``xarm_azimuth_deg`` | ``xarm_azimuth_rad`` |
        | y-arm azimuth         | ``yarm_azimuth_deg`` | ``yarm_azimuth_rad`` |
        | x-arm tilt (optional) | ``xarm_tilt_deg`` | ``xarm_tilt_rad`` |
        | y-arm tilt (optional) | ``yarm_tilt_deg`` | ``yarm_tilt_rad`` |
        +-----------------------+-------------------+-----------+

        ``elevation_m`` is always in metres.  Tilt fields default to ``0.0``
        when absent.

        Args:
            path: Path to a ``.yaml``, ``.yml``, ``.json``, or
                deprecated ``.interferometer`` file.

        Returns:
            A :class:`Network` whose ``detector_names`` contains str entries
            for LAL detector aliases and
            :class:`~gwmock_signal.detector.CustomDetector` entries for
            user-defined geometries.

        Raises:
            ValueError: If the file extension is unsupported, a required
                angle is absent, both ``*_deg`` and ``*_rad`` are given for
                the same angle, or a geometry value is out of range.
        """
        path = Path(path)
        if path.suffix.lower() == ".interferometer":
            from gwmock_signal.io.interferometer_format import interferometer_config_to_custom_detector  # noqa: PLC0415

            detector = interferometer_config_to_custom_detector(path)
            return cls.from_detectors((detector,), name=detector.name)

        data = _load_data(path)

        if not isinstance(data, dict):
            raise ValueError("Network config must be a YAML/JSON mapping at the top level.")
        if "name" not in data:
            raise ValueError("Missing required field: 'name'")
        if "detectors" not in data:
            raise ValueError("Missing required field: 'detectors'")

        detectors_raw = data["detectors"]
        if not isinstance(detectors_raw, list) or len(detectors_raw) == 0:
            raise ValueError("'detectors' must be a non-empty list.")

        detectors: list[str | CustomDetector] = []
        for entry in detectors_raw:
            if not isinstance(entry, dict) or "name" not in entry:
                raise ValueError("Each detector entry must be a mapping with a 'name' field.")
            detectors.append(_detector_from_entry(entry))

        return cls.from_detectors(detectors, name=data["name"])

    # ------------------------------------------------------------------
    # Listing helpers
    # ------------------------------------------------------------------

    @classmethod
    def list_names(cls) -> list[str]:
        """Return a sorted list of all named network and bundled preset aliases."""
        return sorted(set(_NETWORK_PRESETS) | set(_FILE_BACKED_PRESET_ALIASES))

    @classmethod
    def list_lal_detectors(cls) -> list[str]:
        """Return every detector code available in the installed LAL, sorted.

        Returns:
            Sorted list of LAL detector prefix strings
            (e.g. ``['E0', 'E1', 'H1', 'L1', 'V1', ...]``).
        """
        return list_lal_detectors()