lfm-physics 0.1.0__py3-none-any.whl

lfm/__init__.py

@@ -0,0 +1,123 @@
+"""
+LFM — Lattice Field Medium Physics Library
+===========================================
+
+Two governing equations. One integer (χ₀ = 19). All of physics.
+
+Quick start::
+
+    import lfm
+
+    print(lfm.CHI0)        # 19.0
+    print(lfm.KAPPA)       # 0.015873...
+    print(lfm.ALPHA_EM)    # 0.007299... ≈ 1/137.088
+
+    config = lfm.SimulationConfig(grid_size=64)
+    sim = lfm.Simulation(config)
+"""
+
+__version__ = "0.1.0"
+
+from lfm.analysis import (
+    chi_statistics,
+    compute_metrics,
+    count_clusters,
+    energy_components,
+    energy_conservation_drift,
+    interior_mask,
+    total_energy,
+    void_fraction,
+    well_fraction,
+)
+from lfm.config import BoundaryType, FieldLevel, SimulationConfig
+from lfm.constants import (
+    ALPHA_EM,
+    ALPHA_S,
+    CHI0,
+    D_ST,
+    DT_DEFAULT,
+    E_AMPLITUDE_BY_GRID,
+    EPSILON_W,
+    KAPPA,
+    LAMBDA_H,
+    N_COLORS,
+    N_GENERATIONS,
+    OMEGA_LAMBDA,
+    OMEGA_MATTER,
+    SIN2_THETA_W,
+    D,
+)
+from lfm.core.backends import get_backend, gpu_available
+from lfm.core.evolver import Evolver
+from lfm.fields import (
+    equilibrate_chi,
+    equilibrate_from_fields,
+    gaussian_soliton,
+    grid_positions,
+    place_solitons,
+    poisson_solve_fft,
+    seed_noise,
+    sparse_positions,
+    tetrahedral_positions,
+    uniform_chi,
+    wave_kick,
+)
+from lfm.formulas import (
+    mass_table,
+    predict_all,
+)
+from lfm.simulation import Simulation
+
+__all__ = [
+    "__version__",
+    # Constants
+    "CHI0",
+    "D",
+    "D_ST",
+    "KAPPA",
+    "LAMBDA_H",
+    "EPSILON_W",
+    "ALPHA_S",
+    "ALPHA_EM",
+    "OMEGA_LAMBDA",
+    "OMEGA_MATTER",
+    "SIN2_THETA_W",
+    "N_COLORS",
+    "N_GENERATIONS",
+    "DT_DEFAULT",
+    "E_AMPLITUDE_BY_GRID",
+    # Config
+    "SimulationConfig",
+    "FieldLevel",
+    "BoundaryType",
+    # Backends & Simulation
+    "Evolver",
+    "Simulation",
+    "get_backend",
+    "gpu_available",
+    # Fields
+    "gaussian_soliton",
+    "place_solitons",
+    "wave_kick",
+    "poisson_solve_fft",
+    "equilibrate_chi",
+    "equilibrate_from_fields",
+    "seed_noise",
+    "uniform_chi",
+    "tetrahedral_positions",
+    "sparse_positions",
+    "grid_positions",
+    # Analysis
+    "energy_components",
+    "total_energy",
+    "energy_conservation_drift",
+    "chi_statistics",
+    "well_fraction",
+    "void_fraction",
+    "count_clusters",
+    "interior_mask",
+    "compute_metrics",
+    # Formulas
+    "predict_all",
+    "mass_table",
+]

lfm/analysis/__init__.py

@@ -0,0 +1,30 @@
+"""Post-processing analysis: structure detection, energy, spectra."""
+
+from lfm.analysis.energy import (
+    energy_components,
+    energy_conservation_drift,
+    total_energy,
+)
+from lfm.analysis.metrics import compute_metrics
+from lfm.analysis.structure import (
+    chi_statistics,
+    count_clusters,
+    interior_mask,
+    void_fraction,
+    well_fraction,
+)
+
+__all__ = [
+    # energy
+    "energy_components",
+    "total_energy",
+    "energy_conservation_drift",
+    # structure
+    "chi_statistics",
+    "well_fraction",
+    "void_fraction",
+    "count_clusters",
+    "interior_mask",
+    # metrics
+    "compute_metrics",
+]

lfm/analysis/energy.py

@@ -0,0 +1,159 @@
+"""
+Energy Diagnostics
+==================
+
+Three-component energy decomposition for LFM fields:
+    T = ½(∂Ψ/∂t)²    — kinetic energy density
+    G = ½c²|∇Ψ|²     — gradient energy density
+    V = ½χ²|Ψ|²      — potential energy density
+
+Total energy H = ∫(T + G + V) d³x.
+
+Production patterns from exp_sm_02_complex_em_interaction.py and
+lfm_energy_conservation_test.py.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def energy_components(
+    psi_r: NDArray[np.floating],
+    psi_r_prev: NDArray[np.floating],
+    chi: NDArray[np.floating],
+    dt: float,
+    c: float = 1.0,
+    psi_i: NDArray[np.floating] | None = None,
+    psi_i_prev: NDArray[np.floating] | None = None,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Compute three-component energy density fields.
+
+    Supports all field levels:
+    - Real E: psi_r shape (N,N,N), psi_i=None
+    - Complex Ψ: psi_r & psi_i shape (N,N,N)
+    - 3-color Ψₐ: psi_r & psi_i shape (n_colors, N, N, N)
+
+    Parameters
+    ----------
+    psi_r : ndarray
+        Real part of Ψ, current step.
+    psi_r_prev : ndarray
+        Real part of Ψ, previous step.
+    chi : ndarray, shape (N, N, N)
+        χ field at current step.
+    dt : float
+        Timestep for finite-difference time derivative.
+    c : float
+        Wave speed (default 1.0).
+    psi_i : ndarray or None
+        Imaginary part of Ψ, current step.
+    psi_i_prev : ndarray or None
+        Imaginary part, previous step.
+
+    Returns
+    -------
+    kinetic, gradient, potential : ndarray of float64, shape (N, N, N)
+        The three energy density components.
+    """
+    # Time derivative via finite difference
+    dpsi_r_dt = (psi_r.astype(np.float64) - psi_r_prev.astype(np.float64)) / dt
+
+    # Kinetic: ½(∂Ψ/∂t)²
+    if psi_r.ndim == 4:  # color: (n_colors, N, N, N)
+        kinetic = 0.5 * np.sum(dpsi_r_dt**2, axis=0)
+    else:
+        kinetic = 0.5 * dpsi_r_dt**2
+
+    if psi_i is not None and psi_i_prev is not None:
+        dpsi_i_dt = (psi_i.astype(np.float64) - psi_i_prev.astype(np.float64)) / dt
+        if psi_i.ndim == 4:
+            kinetic += 0.5 * np.sum(dpsi_i_dt**2, axis=0)
+        else:
+            kinetic += 0.5 * dpsi_i_dt**2
+
+    # Gradient: ½c²|∇Ψ|²
+    c2 = c**2
+
+    def _grad_sq(f: NDArray) -> NDArray:
+        """Sum of squared gradients over spatial axes."""
+        if f.ndim == 4:  # (n_colors, N, N, N) → grad each color, sum
+            total = np.zeros(f.shape[1:], dtype=np.float64)
+            for a in range(f.shape[0]):
+                for ax in range(3):
+                    g = np.gradient(f[a].astype(np.float64), axis=ax)
+                    total += g**2
+            return total
+        total = np.zeros(f.shape, dtype=np.float64)
+        for ax in range(3):
+            g = np.gradient(f.astype(np.float64), axis=ax)
+            total += g**2
+        return total
+
+    gradient = 0.5 * c2 * _grad_sq(psi_r)
+    if psi_i is not None:
+        gradient += 0.5 * c2 * _grad_sq(psi_i)
+
+    # Potential: ½χ²|Ψ|²
+    chi64 = chi.astype(np.float64)
+    if psi_r.ndim == 4:
+        psi_sq = np.sum(psi_r.astype(np.float64) ** 2, axis=0)
+    else:
+        psi_sq = psi_r.astype(np.float64) ** 2
+    if psi_i is not None:
+        if psi_i.ndim == 4:
+            psi_sq += np.sum(psi_i.astype(np.float64) ** 2, axis=0)
+        else:
+            psi_sq += psi_i.astype(np.float64) ** 2
+
+    potential = 0.5 * chi64**2 * psi_sq
+
+    return kinetic, gradient, potential
+
+
+def total_energy(
+    psi_r: NDArray[np.floating],
+    psi_r_prev: NDArray[np.floating],
+    chi: NDArray[np.floating],
+    dt: float,
+    c: float = 1.0,
+    psi_i: NDArray[np.floating] | None = None,
+    psi_i_prev: NDArray[np.floating] | None = None,
+) -> float:
+    """Compute total integrated energy H = ∫(T + G + V) d³x.
+
+    Parameters are the same as :func:`energy_components`.
+
+    Returns
+    -------
+    float
+        Scalar total energy (sum over all grid points).
+    """
+    T, G, V = energy_components(
+        psi_r, psi_r_prev, chi, dt, c, psi_i, psi_i_prev
+    )
+    return float(np.sum(T + G + V))
+
+
+def energy_conservation_drift(
+    e_initial: float,
+    e_final: float,
+) -> float:
+    """Compute percentage energy drift.
+
+    Parameters
+    ----------
+    e_initial : float
+        Energy at start of simulation.
+    e_final : float
+        Energy at end of simulation.
+
+    Returns
+    -------
+    float
+        |E_final − E_initial| / |E_initial| × 100, or 0 if E_initial ≈ 0.
+    """
+    if abs(e_initial) < 1e-30:
+        return 0.0
+    return abs(e_final - e_initial) / abs(e_initial) * 100.0

lfm/analysis/metrics.py

@@ -0,0 +1,109 @@
+"""
+Combined Metrics
+================
+
+All-in-one snapshot metrics matching the production ``compute_metrics()``
+pattern from primordial_soup and universe_simulator.
+
+Returns a flat dictionary suitable for logging, JSON, or DataFrame rows.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from lfm.analysis.energy import energy_components
+from lfm.analysis.structure import (
+    chi_statistics,
+    count_clusters,
+    void_fraction,
+    well_fraction,
+)
+
+
+def compute_metrics(
+    psi_r: NDArray[np.floating],
+    psi_r_prev: NDArray[np.floating],
+    chi: NDArray[np.floating],
+    dt: float,
+    c: float = 1.0,
+    psi_i: NDArray[np.floating] | None = None,
+    psi_i_prev: NDArray[np.floating] | None = None,
+    interior_mask: NDArray[np.bool_] | None = None,
+    well_threshold: float = 17.0,
+    void_threshold: float = 18.0,
+    cluster_percentile: float = 90.0,
+) -> dict[str, float]:
+    """Compute a full snapshot of simulation metrics.
+
+    Parameters
+    ----------
+    psi_r, psi_r_prev : ndarray
+        Real part of Ψ, current and previous steps.
+    chi : ndarray, shape (N, N, N)
+        The χ field.
+    dt : float
+        Timestep.
+    c : float
+        Wave speed.
+    psi_i, psi_i_prev : ndarray or None
+        Imaginary part of Ψ (None for real fields).
+    interior_mask : ndarray of bool or None
+        Interior region mask (excludes frozen boundary).
+    well_threshold : float
+        χ well threshold.
+    void_threshold : float
+        χ void threshold.
+    cluster_percentile : float
+        Percentile for cluster detection.
+
+    Returns
+    -------
+    dict[str, float]
+        Flat dictionary with all metrics.
+    """
+    # Energy components
+    T, G, V = energy_components(
+        psi_r, psi_r_prev, chi, dt, c, psi_i, psi_i_prev
+    )
+    e_kinetic = float(np.sum(T))
+    e_gradient = float(np.sum(G))
+    e_potential = float(np.sum(V))
+    e_total = e_kinetic + e_gradient + e_potential
+
+    # Chi statistics
+    chi_stats = chi_statistics(chi, interior_mask)
+
+    # Structure
+    wells = well_fraction(chi, well_threshold, interior_mask)
+    voids = void_fraction(chi, void_threshold, interior_mask)
+
+    # |Ψ|² for cluster detection
+    if psi_r.ndim == 4:
+        psi_sq = np.sum(psi_r.astype(np.float64) ** 2, axis=0)
+    else:
+        psi_sq = psi_r.astype(np.float64) ** 2
+    if psi_i is not None:
+        if psi_i.ndim == 4:
+            psi_sq += np.sum(psi_i.astype(np.float64) ** 2, axis=0)
+        else:
+            psi_sq += psi_i.astype(np.float64) ** 2
+
+    clusters = count_clusters(psi_sq, cluster_percentile, interior_mask)
+    psi_sq_total = float(np.sum(psi_sq))
+
+    return {
+        "energy_kinetic": e_kinetic,
+        "energy_gradient": e_gradient,
+        "energy_potential": e_potential,
+        "energy_total": e_total,
+        "chi_min": chi_stats["min"],
+        "chi_max": chi_stats["max"],
+        "chi_mean": chi_stats["mean"],
+        "chi_std": chi_stats["std"],
+        "well_fraction": wells,
+        "void_fraction": voids,
+        "n_clusters": float(clusters),
+        "psi_sq_total": psi_sq_total,
+    }

lfm/analysis/structure.py

@@ -0,0 +1,165 @@
+"""
+Structure Detection
+===================
+
+Detect gravitational wells, voids, and clusters in LFM fields.
+
+Production patterns from primordial_soup_v8_four_forces.py:
+- Wells: χ < WELL_THRESHOLD (17.0)
+- Voids: χ > VOID_THRESHOLD (18.0)
+- Clusters: connected components of high |Ψ|² via scipy.ndimage.label
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy import ndimage
+
+from lfm.constants import VOID_THRESHOLD, WELL_THRESHOLD
+
+
+def chi_statistics(
+    chi: NDArray[np.floating],
+    interior_mask: NDArray[np.bool_] | None = None,
+) -> dict[str, float]:
+    """Compute χ field statistics.
+
+    Parameters
+    ----------
+    chi : ndarray, shape (N, N, N)
+        The χ field.
+    interior_mask : ndarray of bool or None
+        If given, only compute stats where mask is True (excludes boundary).
+
+    Returns
+    -------
+    dict with keys: min, max, mean, std
+    """
+    region = chi[interior_mask] if interior_mask is not None else chi.ravel()
+    return {
+        "min": float(np.min(region)),
+        "max": float(np.max(region)),
+        "mean": float(np.mean(region)),
+        "std": float(np.std(region)),
+    }
+
+
+def well_fraction(
+    chi: NDArray[np.floating],
+    threshold: float = WELL_THRESHOLD,
+    interior_mask: NDArray[np.bool_] | None = None,
+) -> float:
+    """Fraction of grid points in gravitational wells (χ < threshold).
+
+    Parameters
+    ----------
+    chi : ndarray, shape (N, N, N)
+        The χ field.
+    threshold : float
+        Well threshold (default 17.0).
+    interior_mask : ndarray of bool or None
+        If given, only consider interior points.
+
+    Returns
+    -------
+    float
+        Fraction in [0, 1].
+    """
+    region = chi[interior_mask] if interior_mask is not None else chi.ravel()
+    if region.size == 0:
+        return 0.0
+    return float(np.mean(region < threshold))
+
+
+def void_fraction(
+    chi: NDArray[np.floating],
+    threshold: float = VOID_THRESHOLD,
+    interior_mask: NDArray[np.bool_] | None = None,
+) -> float:
+    """Fraction of grid points in voids (χ > threshold).
+
+    Parameters
+    ----------
+    chi : ndarray, shape (N, N, N)
+        The χ field.
+    threshold : float
+        Void threshold (default 18.0).
+    interior_mask : ndarray of bool or None
+        If given, only consider interior points.
+
+    Returns
+    -------
+    float
+        Fraction in [0, 1].
+    """
+    region = chi[interior_mask] if interior_mask is not None else chi.ravel()
+    if region.size == 0:
+        return 0.0
+    return float(np.mean(region > threshold))
+
+
+def count_clusters(
+    field: NDArray[np.floating],
+    threshold_percentile: float = 90.0,
+    interior_mask: NDArray[np.bool_] | None = None,
+) -> int:
+    """Count connected clusters above a percentile threshold.
+
+    Uses scipy.ndimage.label on the binary mask (field > percentile).
+
+    Parameters
+    ----------
+    field : ndarray, shape (N, N, N)
+        Scalar field to cluster (typically |Ψ|²).
+    threshold_percentile : float
+        Percentile threshold (default 90th) above which points count.
+    interior_mask : ndarray of bool or None
+        If given, mask out boundary before labeling.
+
+    Returns
+    -------
+    int
+        Number of connected clusters.
+    """
+    if interior_mask is not None:
+        vals = field[interior_mask]
+    else:
+        vals = field.ravel()
+
+    if vals.size == 0:
+        return 0
+
+    thresh = np.percentile(vals, threshold_percentile)
+    binary = field > thresh
+    if interior_mask is not None:
+        binary = binary & interior_mask
+
+    _, n_clusters = ndimage.label(binary)
+    return int(n_clusters)
+
+
+def interior_mask(
+    N: int,
+    boundary_fraction: float = 0.3,
+) -> NDArray[np.bool_]:
+    """Create a boolean mask for the interior region (excludes frozen boundary).
+
+    Parameters
+    ----------
+    N : int
+        Grid size per axis.
+    boundary_fraction : float
+        Fraction of grid radius for boundary shell.
+
+    Returns
+    -------
+    ndarray of bool, shape (N, N, N)
+        True in the interior, False in the boundary shell.
+    """
+    center = N / 2.0
+    radius = center * (1.0 - boundary_fraction)
+    x = np.arange(N, dtype=np.float64)
+    X, Y, Z = np.meshgrid(x, x, x, indexing="ij")
+    dist = np.sqrt((X - center) ** 2 + (Y - center) ** 2 + (Z - center) ** 2)
+    return dist <= radius