gragra 0.2.0rc1__py3-none-any.whl

gragra/__init__.py

@@ -0,0 +1,46 @@
+"""gragra: A Python package for gravitational perturbation calculation."""
+
+from typing import TYPE_CHECKING
+
+from gragra.constants import G_SI
+from gragra.gravity_sources import PointMass, PointMassCloud, WeightedPointSource
+from gragra.observables import (
+    coherent_acceleration_csd,
+    coherent_gravitoelastic_tensor,
+    coherent_point_acceleration,
+    coherent_point_gravity_gradient,
+    displacement_field_acceleration,
+    displacement_transfer_acceleration,
+    point_acceleration,
+    point_gravity_gradient,
+    point_potential,
+)
+
+__all__ = [
+    "G_SI",
+    "WeightedPointSource",
+    "PointMass",
+    "PointMassCloud",
+    "TargetPoints",
+    "point_potential",
+    "point_acceleration",
+    "point_gravity_gradient",
+    "coherent_point_acceleration",
+    "coherent_point_gravity_gradient",
+    "coherent_gravitoelastic_tensor",
+    "coherent_acceleration_csd",
+    "displacement_transfer_acceleration",
+    "displacement_field_acceleration",
+]
+
+if TYPE_CHECKING:
+    from gragra.targets._high_points import TargetPoints
+
+
+def __getattr__(name: str):
+    """Load high-level target types only when callers request them."""
+    if name == "TargetPoints":
+        from gragra.targets._high_points import TargetPoints
+
+        return TargetPoints
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

gragra/_analytic_evaluation.py

@@ -0,0 +1,413 @@
+"""Shared evaluation bridge for analytic model families."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from importlib.metadata import version
+from platform import python_version
+from types import MappingProxyType
+from typing import TypeAlias
+
+import numpy as np
+import pandas as pd
+from astropy import units as u
+from astropy.table import QTable
+from gwexpy.frequencyseries import FrequencySeriesMatrix
+
+from gragra._interactions import Newtonian
+from gragra._time_matrix import make_time_matrix
+from gragra.constants import G_SI
+from gragra.exceptions import ConvergenceError, NumericalDiagnostic
+from gragra.geometry._frame import Frame
+from gragra.results import GravityResult
+from gragra.results._context import EvaluationContext
+from gragra.results._evaluation import EvaluationResult
+from gragra.results._record import OBSERVABLES, EvaluationRecord
+from gragra.results._representation import (
+    StaticRepresentation,
+    TimeSeriesRepresentation,
+)
+from gragra.results._spectral import PhasorRepresentation
+
+NativeValues: TypeAlias = Mapping[str, object]
+
+_UNITS = {
+    "potential": u.m**2 / u.s**2,
+    "acceleration": u.m / u.s**2,
+    "gradient": u.s**-2,
+}
+_COMPONENTS = {
+    "potential": ("potential",),
+    "acceleration": ("x", "y", "z"),
+    "gradient": ("xx", "xy", "xz", "yx", "yy", "yz", "zx", "zy", "zz"),
+}
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class NativeEvaluation:
+    """G-free family output before common frame transforms and SI packaging."""
+
+    values: NativeValues
+    diagnostics: tuple[NumericalDiagnostic, ...]
+
+    def __init__(
+        self,
+        values: Mapping[str, object],
+        diagnostics: tuple[NumericalDiagnostic, ...] = (),
+    ) -> None:
+        if not isinstance(values, Mapping):
+            raise TypeError("native values must be an observable mapping")
+        snapshot = dict(values)
+        if any(
+            not isinstance(name, str) or name not in OBSERVABLES for name in snapshot
+        ):
+            raise ValueError("native values contain an unknown observable")
+        if isinstance(diagnostics, (str, bytes)):
+            raise TypeError("diagnostics must be an iterable of NumericalDiagnostic")
+        try:
+            diagnostic_snapshot = tuple(diagnostics)
+        except TypeError as exc:
+            raise TypeError(
+                "diagnostics must be an iterable of NumericalDiagnostic"
+            ) from exc
+        if any(
+            not isinstance(item, NumericalDiagnostic) for item in diagnostic_snapshot
+        ):
+            raise TypeError("diagnostics must contain NumericalDiagnostic values")
+        object.__setattr__(self, "values", MappingProxyType(snapshot))
+        object.__setattr__(self, "diagnostics", diagnostic_snapshot)
+
+
+NativeCallback: TypeAlias = Callable[[np.ndarray, tuple[str, ...]], NativeEvaluation]
+
+
+@dataclass(frozen=True, eq=False, slots=True, init=False)
+class AnalyticEvaluation:
+    """Shared static, phasor, and time-series evaluation adapter.
+
+    Family callbacks return G-free arrays. This adapter owns validation of the
+    shared context, component transforms, one application of ``G_SI``, and
+    native result construction. Family-specific physics and target rejection
+    stay in the model callback and optional validator.
+    """
+
+    context: EvaluationContext
+    computation_frame: Frame
+    _target_positions_bytes: bytes
+    _target_count: int
+    evaluate_native: NativeCallback
+    validate_targets: Callable[[np.ndarray], object] | None
+
+    def __init__(
+        self,
+        *,
+        context: EvaluationContext,
+        computation_frame: Frame,
+        target_positions_m: object,
+        evaluate_native: NativeCallback,
+        validate_targets: Callable[[np.ndarray], object] | None = None,
+    ) -> None:
+        if not isinstance(context, EvaluationContext):
+            raise TypeError("context must be an EvaluationContext")
+        if not isinstance(getattr(context.model_spec, "interaction", None), Newtonian):
+            raise TypeError("analytic evaluation requires a Newtonian interaction")
+        if not isinstance(computation_frame, Frame):
+            raise TypeError("computation_frame must be a Frame")
+        if not callable(evaluate_native):
+            raise TypeError("evaluate_native must be callable")
+        if validate_targets is not None and not callable(validate_targets):
+            raise TypeError("validate_targets must be callable or None")
+        context.targets.frame._path_to(computation_frame)
+        computation_frame._path_to(context.frame)
+
+        raw = np.asarray(target_positions_m)
+        if np.iscomplexobj(raw):
+            raise ValueError("target_positions_m must contain only real coordinates")
+        if np.issubdtype(raw.dtype, np.bool_):
+            raise TypeError("target_positions_m must not contain bool values")
+        try:
+            positions = np.asarray(raw, dtype=np.float64)
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise TypeError("target_positions_m must contain real coordinates") from exc
+        expected_shape = (len(context.targets), 3)
+        if positions.shape != expected_shape:
+            raise ValueError(
+                "target_positions_m must have shape "
+                f"{expected_shape}, got {positions.shape}"
+            )
+        if not np.isfinite(positions).all():
+            raise ValueError("target_positions_m must contain only finite coordinates")
+
+        object.__setattr__(self, "context", context)
+        object.__setattr__(self, "computation_frame", computation_frame)
+        object.__setattr__(self, "_target_positions_bytes", positions.copy().tobytes())
+        object.__setattr__(self, "_target_count", len(positions))
+        object.__setattr__(self, "evaluate_native", evaluate_native)
+        object.__setattr__(self, "validate_targets", validate_targets)
+
+    @property
+    def target_positions_m(self) -> np.ndarray:
+        """Read-only positions in the numerical kernel's computation frame."""
+        return np.frombuffer(self._target_positions_bytes, dtype=np.float64).reshape(
+            self._target_count, 3
+        )
+
+    @property
+    def model_spec(self):
+        return self.context.model_spec
+
+    @property
+    def parameters(self) -> QTable:
+        value = getattr(self.model_spec, "parameters", None)
+        return QTable() if value is None else value
+
+    @property
+    def formulas(self) -> pd.DataFrame:
+        value = getattr(self.model_spec, "formulas", None)
+        return pd.DataFrame() if value is None else value
+
+    @property
+    def references(self) -> pd.DataFrame:
+        value = getattr(self.model_spec, "references", None)
+        return pd.DataFrame() if value is None else value
+
+    def validate(self) -> None:
+        """Recheck shared interpretation and then run family target checks."""
+        self.context.validate()
+        if not isinstance(
+            getattr(self.context.model_spec, "interaction", None), Newtonian
+        ):
+            raise TypeError("analytic evaluation requires a Newtonian interaction")
+        positions = self.target_positions_m
+        if (
+            positions.shape != (len(self.context.targets), 3)
+            or not np.isfinite(positions).all()
+        ):
+            raise ValueError("analytic evaluation target coordinates are invalid")
+        self.context.targets.frame._path_to(self.computation_frame)
+        self.computation_frame._path_to(self.context.frame)
+        if self.validate_targets is not None:
+            self.validate_targets(positions)
+
+    def run(self) -> EvaluationResult:
+        """Evaluate once and return all requested observables or raise."""
+        self.validate()
+        try:
+            native = self.evaluate_native(
+                self.target_positions_m, self.context.observables
+            )
+        except Exception as cause:
+            raise self._evaluation_error(cause) from cause
+        if not isinstance(native, NativeEvaluation):
+            raise TypeError("evaluate_native must return NativeEvaluation")
+        self._validate_diagnostics(native.diagnostics)
+        if any(
+            diagnostic.termination in {"resource_limit", "uncertainty_unresolved"}
+            for diagnostic in native.diagnostics
+        ):
+            raise ValueError(
+                "successful evaluations cannot contain failed numerical diagnostics"
+            )
+        arrays = self._validate_native_values(native.values)
+        arrays = self._rotate_and_apply_g(arrays)
+        values = self._package_values(arrays)
+        return EvaluationResult(
+            values=GravityResult(**values),
+            evaluation=self,
+            record=self._record(native.diagnostics),
+        )
+
+    def _evaluation_error(self, cause: Exception):
+        from gragra.evaluation import EvaluationError
+
+        target_index = 0 if self._target_count else None
+        observable = self.context.observables[0]
+        if isinstance(cause, ConvergenceError):
+            try:
+                self._validate_diagnostics(cause.diagnostics)
+            except (TypeError, ValueError):
+                pass
+            else:
+                failure = next(
+                    diagnostic
+                    for diagnostic in cause.diagnostics
+                    if diagnostic.termination
+                    in {"resource_limit", "uncertainty_unresolved"}
+                )
+                target_index = failure.target_index
+                observable = failure.observable
+        target_id = (
+            None if target_index is None else self.context.targets.ids[target_index]
+        )
+        return EvaluationError(
+            target_id=target_id,
+            source_index=None,
+            observables=self.context.observables,
+            observable=observable,
+            cause=cause,
+        )
+
+    def _validate_diagnostics(
+        self, diagnostics: tuple[NumericalDiagnostic, ...]
+    ) -> None:
+        for diagnostic in diagnostics:
+            index = diagnostic.target_index
+            if index >= len(self.context.targets):
+                raise ValueError("diagnostic target_index is outside context targets")
+            expected_id = self.context.targets.ids[index]
+            if diagnostic.target_id != expected_id:
+                raise ValueError(
+                    "diagnostic target_id must match context target ID at target_index"
+                )
+
+    def _validate_native_values(
+        self, values: Mapping[str, object]
+    ) -> dict[str, np.ndarray]:
+        names = self.context.observables
+        if set(values) != set(names):
+            raise ValueError("native values must match requested observables exactly")
+        representation = self.context.representation
+        target_count = len(self.context.targets)
+        if isinstance(representation, StaticRepresentation):
+            axis_count = None
+        elif isinstance(representation, PhasorRepresentation):
+            axis_count = len(self.context.frequencies_hz or ())
+        elif isinstance(representation, TimeSeriesRepresentation):
+            sampling = self.context.time_sampling
+            if sampling is None:
+                raise ValueError("time_series context requires TimeSampling")
+            axis_count = sampling.count
+        else:
+            raise TypeError("analytic representation is unsupported")
+
+        arrays: dict[str, np.ndarray] = {}
+        for name in names:
+            raw = np.asarray(values[name])
+            if not np.issubdtype(raw.dtype, np.number):
+                raise TypeError(f"native {name} values must be numeric")
+            if isinstance(representation, StaticRepresentation):
+                expected_shape = {
+                    "potential": (target_count,),
+                    "acceleration": (target_count, 3),
+                    "gradient": (target_count, 3, 3),
+                }[name]
+                complex_required = False
+            else:
+                expected_shape = (
+                    target_count,
+                    len(_COMPONENTS[name]),
+                    axis_count,
+                )
+                complex_required = isinstance(representation, PhasorRepresentation)
+            if raw.shape != expected_shape:
+                raise ValueError(
+                    f"native {name} values must have shape {expected_shape}, "
+                    f"got {raw.shape}"
+                )
+            if complex_required and not np.iscomplexobj(raw):
+                raise ValueError(f"native phasor {name} values must be complex")
+            if not complex_required and np.iscomplexobj(raw):
+                raise ValueError(f"native {name} values must be real")
+            dtype = np.complex128 if complex_required else np.float64
+            try:
+                array = np.asarray(raw, dtype=dtype)
+            except (TypeError, ValueError, OverflowError) as exc:
+                raise ValueError(f"native {name} values cannot be represented") from exc
+            if not np.isfinite(array).all():
+                raise ValueError(f"native {name} values must be finite")
+            arrays[name] = array
+        return arrays
+
+    def _rotate_and_apply_g(
+        self, arrays: Mapping[str, np.ndarray]
+    ) -> dict[str, np.ndarray]:
+        rotation = self.computation_frame.rotation_to(self.context.frame)
+        representation = self.context.representation
+        result: dict[str, np.ndarray] = {}
+        for name, values in arrays.items():
+            with np.errstate(over="ignore", invalid="ignore"):
+                if name == "potential":
+                    output = G_SI * values
+                elif isinstance(representation, StaticRepresentation):
+                    if name == "acceleration":
+                        output = G_SI * np.einsum("ij,nj->ni", rotation, values)
+                    else:
+                        output = G_SI * np.einsum(
+                            "ia,nab,jb->nij", rotation, values, rotation
+                        )
+                elif name == "acceleration":
+                    output = G_SI * np.einsum("ij,njt->nit", rotation, values)
+                else:
+                    count, _, axis_count = values.shape
+                    tensors = values.reshape(count, 3, 3, axis_count)
+                    output = G_SI * np.einsum(
+                        "ia,nabt,jb->nijt", rotation, tensors, rotation
+                    ).reshape(count, 9, axis_count)
+            if not np.isfinite(output).all():
+                raise ValueError(f"SI {name} values became non-finite")
+            result[name] = output
+        return result
+
+    def _package_values(self, arrays: Mapping[str, np.ndarray]) -> dict[str, object]:
+        representation = self.context.representation
+        if isinstance(representation, StaticRepresentation):
+            return {
+                name: arrays[name] * _UNITS[name] for name in self.context.observables
+            }
+        if isinstance(representation, PhasorRepresentation):
+            matrices = {}
+            frequencies = (
+                np.asarray(self.context.frequencies_hz, dtype=np.float64) * u.Hz
+            )
+            target_ids = self.context.targets.ids
+            for name in self.context.observables:
+                raw = arrays[name]
+                components = _COMPONENTS[name]
+                matrices[name] = FrequencySeriesMatrix(
+                    raw.copy(),
+                    frequencies=frequencies,
+                    units=np.full(
+                        (len(target_ids), len(components)), _UNITS[name], dtype=object
+                    ),
+                    rows=list(target_ids),
+                    cols=list(components),
+                    name=f"Gen1 {name}",
+                )
+            return matrices
+        if isinstance(representation, TimeSeriesRepresentation):
+            sampling = self.context.time_sampling
+            if sampling is None:
+                raise ValueError("time_series context requires TimeSampling")
+            return {
+                name: make_time_matrix(
+                    arrays[name],
+                    sampling=sampling,
+                    unit=_UNITS[name],
+                    rows=self.context.targets.ids,
+                    cols=_COMPONENTS[name],
+                    name=f"Gen1 {name}",
+                )
+                for name in self.context.observables
+            }
+        raise TypeError("analytic representation is unsupported")
+
+    @staticmethod
+    def _record(diagnostics: tuple[NumericalDiagnostic, ...]) -> EvaluationRecord:
+        return EvaluationRecord(
+            backend="gen1_analytic_native",
+            versions={
+                "gragra": version("gragra"),
+                "python": python_version(),
+                "numpy": np.__version__,
+                "scipy": version("scipy"),
+                "astropy": version("astropy"),
+                "gwexpy": version("gwexpy"),
+            },
+            gravitational_constant_si=G_SI,
+            g_applications=1,
+            numerical_diagnostics=diagnostics,
+        )
+
+
+__all__ = ["AnalyticEvaluation", "NativeEvaluation"]

gragra/_arrays.py

@@ -0,0 +1,194 @@
+"""Internal array normalization and validation helpers."""
+
+import numpy as np
+
+from gragra.array_types import ComplexArray, FloatArray
+
+
+def as_xyz_vector(name: str, value: list | tuple | np.ndarray) -> FloatArray:
+    """Normalize and validate a single 3D vector.
+
+    Expects a value convertable to a float64 array of shape (3,).
+    Sets the writeable flag of the returned array to False (read-only).
+
+    Parameters
+    ----------
+    name : str
+        Parameter name for error messages.
+    value : array-like
+        The input coordinates, e.g., [x, y, z].
+
+    Returns
+    -------
+    FloatArray
+        A read-only float64 array of shape (3,).
+    """
+    try:
+        arr = np.asarray(value, dtype=np.float64)
+    except (ValueError, TypeError) as e:
+        raise TypeError(f"{name} must be numeric convertible to float64: {e}") from e
+
+    if arr.shape != (3,):
+        raise ValueError(f"{name} must have shape (3,), got {arr.shape}")
+
+    if not np.isfinite(arr).all():
+        raise ValueError(f"{name} must contain only finite numbers")
+
+    # Defensive copy and set to read-only
+    arr = arr.copy()
+    arr.setflags(write=False)
+    return arr
+
+
+def as_xyz_table(name: str, value: list | tuple | np.ndarray) -> FloatArray:
+    """Normalize and validate a table of 3D vectors.
+
+    Expects a value convertable to a float64 array of shape (N, 3).
+    Strictly rejects shape (3,).
+    Sets the writeable flag of the returned array to False (read-only).
+
+    Parameters
+    ----------
+    name : str
+        Parameter name for error messages.
+    value : array-like
+        The input coordinates table, e.g., [[x1, y1, z1], [x2, y2, z2], ...].
+
+    Returns
+    -------
+    FloatArray
+        A read-only float64 array of shape (N, 3).
+    """
+    is_1d = False
+    try:
+        val_arr = np.asarray(value)
+        if val_arr.ndim == 1:
+            is_1d = True
+    except (ValueError, TypeError):
+        pass
+
+    if is_1d:
+        raise ValueError(f"{name} must be a 2D table of shape (N, 3), not a 1D vector")
+
+    try:
+        arr = np.asarray(value, dtype=np.float64)
+    except (ValueError, TypeError) as e:
+        raise TypeError(f"{name} must be numeric convertible to float64: {e}") from e
+
+    if arr.ndim != 2 or arr.shape[1] != 3:
+        raise ValueError(f"{name} must have shape (N, 3), got {arr.shape}")
+
+    if not np.isfinite(arr).all():
+        raise ValueError(f"{name} must contain only finite numbers")
+
+    arr = arr.copy()
+    arr.setflags(write=False)
+    return arr
+
+
+def as_weights(
+    name: str, value: list | tuple | np.ndarray
+) -> FloatArray | ComplexArray:
+    """Normalize and validate weight vectors (real or complex).
+
+    Expects a value convertable to float64 or complex128 array of shape (N,).
+    Keeps real inputs as float64 and complex inputs as complex128.
+    Sets the writeable flag of the returned array to False (read-only).
+
+    Parameters
+    ----------
+    name : str
+        Parameter name for error messages.
+    value : array-like
+        The weights array, e.g. [w1, w2, ...].
+
+    Returns
+    -------
+    FloatArray or ComplexArray
+        A read-only array of shape (N,).
+    """
+    raw_arr = np.asarray(value)
+
+    # Determine appropriate dtype (preserve complex if input is complex)
+    dtype = np.complex128 if np.iscomplexobj(raw_arr) else np.float64
+
+    try:
+        arr = np.asarray(value, dtype=dtype)
+    except (ValueError, TypeError) as e:
+        raise TypeError(
+            f"{name} must be convertible to float64 or complex128: {e}"
+        ) from e
+
+    if arr.ndim != 1:
+        raise ValueError(
+            f"{name} must be a 1D array of shape (N,), got shape {arr.shape}"
+        )
+
+    if not np.isfinite(arr).all():
+        raise ValueError(f"{name} must contain only finite numbers")
+
+    arr = arr.copy()
+    arr.setflags(write=False)
+    return arr
+
+
+def as_index_table(
+    name: str, value: list | tuple | np.ndarray, n_max: int
+) -> np.ndarray:
+    """Normalize and validate an integer connectivity table of shape (Nt, 3).
+
+    Expects integer vertex indices in the half-open range ``[0, n_max)``.
+    Returns a read-only ``np.intp`` array of shape (Nt, 3), independent of the
+    input integer dtype, so callers obtain a canonical connectivity table.
+
+    This consolidates the integer-connectivity validation that is otherwise
+    duplicated across the field/adapter helpers; it rejects bool, non-integer
+    dtype, wrong shape, and both lower (``< 0``) and upper (``>= n_max``)
+    out-of-range indices.
+
+    Parameters
+    ----------
+    name : str
+        Parameter name for error messages.
+    value : array-like
+        The connectivity table, e.g. [[i0, i1, i2], ...].
+    n_max : int
+        Exclusive upper bound for indices (typically the number of vertices).
+
+    Returns
+    -------
+    np.ndarray
+        A read-only ``np.intp`` array of shape (Nt, 3).
+    """
+    _check_no_bool(value, name)
+
+    raw = np.asarray(value)
+    if raw.dtype.kind not in "iu":
+        raise TypeError(f"{name} must be of integer type, got {raw.dtype}")
+
+    if raw.ndim != 2 or raw.shape[1] != 3:
+        raise ValueError(f"{name} must have shape (Nt, 3), got {raw.shape}")
+
+    arr = raw.astype(np.intp, copy=True)
+    if arr.size > 0 and ((arr < 0).any() or (arr >= n_max).any()):
+        raise ValueError(f"{name} indices must be within [0, {n_max})")
+
+    arr.setflags(write=False)
+    return arr
+
+
+def _check_no_bool(val, name):
+    """Helper to raise TypeError if any boolean value is found in inputs."""
+    if isinstance(val, (bool, np.bool_)):
+        raise TypeError(f"{name} must not contain bool")
+    if hasattr(val, "dtype"):
+        if val.dtype.kind == "b":
+            raise TypeError(f"{name} must not contain bool")
+        if val.dtype.kind in "fiuc":
+            return
+    if isinstance(val, np.ndarray):
+        for x in val.flat:
+            _check_no_bool(x, name)
+    elif isinstance(val, (list, tuple)):
+        for x in val:
+            _check_no_bool(x, name)