pylgframework 0.1.0__py3-none-any.whl

pylgframework/__init__.py

@@ -0,0 +1,8 @@
+"""pylgframework: Local Group barycentre with propagated observational uncertainty."""
+from . import fiducials
+from .barycentre import Result, barycentre
+from .compare import Comparison, compare
+from .sampling import DEFAULT_SIGMAS
+
+__version__ = "0.1.0"
+__all__ = ["barycentre", "compare", "fiducials", "Result", "Comparison", "DEFAULT_SIGMAS"]

pylgframework/barycentre.py

@@ -0,0 +1,169 @@
+"""Barycentre of the Local Group with propagated observational uncertainty."""
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import astropy.units as u
+import numpy as np
+import pandas as pd
+from astropy.coordinates import ICRS, SkyCoord
+
+from .constants import KMS, MEMBERSHIPS, NAMES, V_MW_CMB
+from .fiducials import Fiducial, get as _get_fiducial
+from .frames import galactocentric_frame, helio_to_galactocentric
+from .sampling import DEFAULT_SIGMAS, sample_ensemble
+
+
+def _resolve(source):
+    """-> (name, obs dict, zero_mass tuple)."""
+    if isinstance(source, str):
+        source = _get_fiducial(source)
+    if isinstance(source, Fiducial):
+        return source.name, source.obs, source.zero_mass
+    if isinstance(source, dict):
+        return "custom", source, ()
+    raise TypeError("source must be a Fiducial, a fiducial name or an observables dict")
+
+
+def phase_space(obs_list, zero_mass=()):
+    """Masses (K,4), positions (K,4,3) kpc, velocities (K,4,3) km/s (MW at rest at the origin)."""
+    K = len(obs_list)
+    m = np.array([[o[nm]["m"] for nm in NAMES] for o in obs_list], float)
+    r, v = np.zeros((K, 4, 3)), np.zeros((K, 4, 3))
+    for j, nm in enumerate(NAMES):
+        if nm == "MilkyWay":
+            continue
+        g = lambda k: [o[nm][k] for o in obs_list]
+        r[:, j], v[:, j] = helio_to_galactocentric(g("ra"), g("dec"), g("mu"),
+                                                   g("pmra"), g("pmdec"), g("vlos"))
+    for nm in zero_mass:
+        m[:, NAMES.index(nm)] = 0.0
+    return m, r, v
+
+
+def _bc(m, r, v, idx):
+    mm = m[:, idx]
+    M = mm.sum(1)[:, None]
+    return (mm[..., None] * r[:, idx]).sum(1) / M, (mm[..., None] * v[:, idx]).sum(1) / M
+
+
+def build_cloud(m, r, v, membership="4"):
+    """DataFrame with the barycentre of every realization and the membership diagnostics."""
+    idx = MEMBERSHIPS[membership]
+    rb, vb = _bc(m, r, v, idx)
+    c = SkyCoord(x=rb[:, 0] * u.kpc, y=rb[:, 1] * u.kpc, z=rb[:, 2] * u.kpc,
+                 frame=galactocentric_frame())
+    icrs, gal = c.transform_to(ICRS()), c.transform_to("galactic")
+    xyz = icrs.cartesian.xyz.to_value(u.kpc)
+    df = pd.DataFrame({
+        "bc0_x": rb[:, 0], "bc0_y": rb[:, 1], "bc0_z": rb[:, 2],
+        "bc0_vx": vb[:, 0], "bc0_vy": vb[:, 1], "bc0_vz": vb[:, 2],
+        "bc0_ra": icrs.ra.deg, "bc0_dec": icrs.dec.deg,
+        "bc0_dist": icrs.distance.to_value(u.kpc),
+        "bc0_l": gal.l.deg, "bc0_b": gal.b.deg,
+        "bc0_icrs_x": xyz[0], "bc0_icrs_y": xyz[1], "bc0_icrs_z": xyz[2]})
+    bcs = {t: _bc(m, r, v, i) for t, i in MEMBERSHIPS.items()}
+    (r2, v2), (r3, v3), (r4, v4), (r5, v5) = bcs["2"], bcs["3M"], bcs["4"], bcs["3L"]
+    n = lambda x: np.linalg.norm(x, axis=1)
+    df["shift_M33_kpc"], df["dv_M33_kms"] = n(r3 - r2), n(v3 - v2)
+    df["shift_LMC_kpc"], df["dv_LMC_kms"] = n(r5 - r2), n(v5 - v2)
+    df["shift_M33_LMC_kpc"], df["dv_M33_LMC_kms"] = n(r4 - r3), n(v4 - v3)
+    df["shift_2to4_kpc"], df["dv_2to4_kms"] = n(r4 - r2), n(v4 - v2)
+    for T in (5.0, 10.0):
+        df[f"drift_2to4_{T:g}Gyr_kpc"] = n((r4 - r2) + (v4 - v2) * KMS * T)
+    for tag, (_, vv) in bcs.items():
+        df[f"vcmb_{tag}_kms"] = n(vv + V_MW_CMB[None, :])
+    return df
+
+
+@dataclass
+class Result:
+    """Barycentre cloud and its summary statistics."""
+    cloud: pd.DataFrame
+    nominal_position: np.ndarray          # kpc, Galactocentric, unsampled central values
+    nominal_velocity: np.ndarray          # km/s
+    fiducial: str
+    n: int
+    seed: int
+    membership: str
+    sigmas: Any
+
+    @property
+    def positions(self):
+        return self.cloud[["bc0_x", "bc0_y", "bc0_z"]].to_numpy()
+
+    @property
+    def velocities(self):
+        return self.cloud[["bc0_vx", "bc0_vy", "bc0_vz"]].to_numpy()
+
+    @property
+    def median_position(self):
+        return np.median(self.positions, axis=0)
+
+    @property
+    def median_velocity(self):
+        return np.median(self.velocities, axis=0)
+
+    @property
+    def covariance(self):
+        return np.cov(self.positions.T)
+
+    @property
+    def principal_axes(self):
+        """(semiaxes 1-sigma, descending; unit vectors as columns)."""
+        w, U = np.linalg.eigh(self.covariance)
+        o = np.argsort(w)[::-1]
+        return np.sqrt(w[o]), U[:, o]
+
+    @property
+    def axes(self):
+        return self.principal_axes[0]
+
+    def vcmb(self, membership="4"):
+        """(16th, 50th, 84th percentile) of the barycentre speed w.r.t. the CMB, km/s."""
+        return tuple(np.percentile(self.cloud[f"vcmb_{membership}_kms"], [16, 50, 84]))
+
+    def summary(self):
+        a = self.axes
+        c = self.cloud
+        q = self.vcmb(self.membership)
+        return "\n".join([
+            f"Local Group barycentre | fiducial: {self.fiducial} | members: {self.membership} "
+            f"| N = {self.n}, seed = {self.seed}",
+            f"  median position (Galactocentric, kpc): {np.round(self.median_position, 1)}",
+            f"  median velocity (MW rest frame, km/s): {np.round(self.median_velocity, 1)}",
+            f"  1-sigma principal axes (kpc)          : {np.round(a, 1)}",
+            f"  median ICRS: RA = {c.bc0_ra.median():.1f} deg, Dec = {c.bc0_dec.median():+.1f} deg, "
+            f"d = {c.bc0_dist.median():.0f} kpc",
+            f"  speed w.r.t. the CMB (16/50/84 %)      : {np.round(q, 1)} km/s",
+            "Assumptions:",
+            "  * Gaussian sampling truncated at +-2 sigma (effective std ~0.88 sigma);",
+            "  * sky positions held fixed; MW at rest at the origin of the Galactocentric frame;",
+            "  * the output is the uncertainty INDUCED by the declared errors, not a complete",
+            "    physical uncertainty region.",
+        ])
+
+    def __repr__(self):
+        return self.summary()
+
+
+def barycentre(source, n=1000, seed=2000, sigmas: Optional[dict] = None, membership="4"):
+    """Barycentre of the Local Group with Monte Carlo uncertainty.
+
+    Parameters
+    ----------
+    source : Fiducial, str or dict
+        A fiducial (``fiducials.WU``), its name, or a dict of heliocentric observables
+        with the structure of ``Fiducial.obs``.
+    n : number of Monte Carlo realizations.
+    seed : realization ``i`` uses ``default_rng([seed, i])`` (reproducible one by one).
+    sigmas : 1-sigma uncertainties; defaults to Table 1 of Wu et al. (2026).
+    membership : ``"2"`` (MW+M31), ``"3M"`` (+M33), ``"3L"`` (+LMC) or ``"4"`` (all).
+    """
+    name, base, zero = _resolve(source)
+    sig = DEFAULT_SIGMAS if sigmas is None else sigmas
+    obs_list = sample_ensemble(base, n, seed, sig)
+    m, r, v = phase_space(obs_list, zero)
+    df = build_cloud(m, r, v, membership)
+    m0, r0, v0 = phase_space([base], zero)
+    (rn, vn) = _bc(m0, r0, v0, MEMBERSHIPS[membership])
+    return Result(df, rn[0], vn[0], name, n, seed, membership, sig)

pylgframework/compare.py

@@ -0,0 +1,37 @@
+"""Paired comparison between two fiducials (identical random draws)."""
+from dataclasses import dataclass
+
+import numpy as np
+
+from .barycentre import Result, barycentre
+from .constants import MEMBERSHIPS
+
+
+@dataclass
+class Comparison:
+    a: Result
+    b: Result
+    offset_kpc: float                 # |nominal_b - nominal_a|
+    offset_principal: np.ndarray      # offset in the principal-axis frame of ``a`` (kpc)
+    offset_sigma: float               # |component along the major axis of a| / a1
+    dvcmb: dict                       # median v_CMB(b) - median v_CMB(a), per membership (km/s)
+
+    def __repr__(self):
+        d = ", ".join(f"{k}: {v:+.0f}" for k, v in self.dvcmb.items())
+        return (f"Comparison({self.a.fiducial} -> {self.b.fiducial}): offset = {self.offset_kpc:.1f} kpc "
+                f"({self.offset_sigma:.1f} sigma along the major axis of {self.a.fiducial}); "
+                f"dv_CMB [km/s] = {d}")
+
+
+def compare(a, b, n=1000, seed=3000, sigmas=None, membership="4"):
+    """Paired experiment: realization i of both fiducials uses the same random draw,
+    so differences measure the effect of the adopted central values, not Monte Carlo noise.
+    """
+    ra = barycentre(a, n=n, seed=seed, sigmas=sigmas, membership=membership)
+    rb = barycentre(b, n=n, seed=seed, sigmas=sigmas, membership=membership)
+    d = rb.nominal_position - ra.nominal_position
+    axes, U = ra.principal_axes
+    proj = d @ U
+    dv = {t: float(rb.cloud[f"vcmb_{t}_kms"].median() - ra.cloud[f"vcmb_{t}_kms"].median())
+          for t in MEMBERSHIPS}
+    return Comparison(ra, rb, float(np.linalg.norm(d)), proj, float(abs(proj[0]) / axes[0]), dv)

pylgframework/constants.py

@@ -0,0 +1,34 @@
+"""Single source of truth for the constants shared by the whole package."""
+import numpy as np
+
+KMS = 1.022712165                      # 1 km/s in kpc/Gyr
+
+# Solar Galactocentric frame (Sawala et al. 2025; Wu et al. 2026)
+SUN_R0 = 8.122                         # kpc
+SUN_V = (12.9, 245.6, 7.78)            # km/s
+
+# Truncation of the Gaussian sampling, in sigmas
+TRUNC = 2.0
+
+# Solar dipole w.r.t. the CMB rest frame:
+# Planck 2015 results. V. LFI calibration (Planck Collaboration 2016, A&A 594, A5).
+V_SUN_CMB = 369.82                     # km/s
+L_CMB, B_CMB = 264.021, 48.253         # deg (Galactic l, b)
+
+_U_SUN_CMB = V_SUN_CMB * np.array([
+    np.cos(np.deg2rad(B_CMB)) * np.cos(np.deg2rad(L_CMB)),
+    np.cos(np.deg2rad(B_CMB)) * np.sin(np.deg2rad(L_CMB)),
+    np.sin(np.deg2rad(B_CMB))])
+# Velocity of the MW (origin of the Galactocentric frame) w.r.t. the CMB
+V_MW_CMB = _U_SUN_CMB - np.array(SUN_V)
+
+# Body order is part of the public contract (indices used everywhere)
+NAMES = ("MilkyWay", "M31", "M33", "LMC")
+
+# Membership definitions: tag -> indices into NAMES
+MEMBERSHIPS = {
+    "2": (0, 1),            # MW + M31
+    "3M": (0, 1, 2),        # MW + M31 + M33
+    "3L": (0, 1, 3),        # MW + M31 + LMC
+    "4": (0, 1, 2, 3),      # MW + M31 + M33 + LMC
+}

pylgframework/fiducials.py

@@ -0,0 +1,114 @@
+"""Literature fiducials with explicit provenance.
+
+Each fiducial stores HELIOCENTRIC observables in the format used by the
+sampler (``mu`` distance modulus, ``pmra``/``pmdec`` in uas/yr, ``vlos`` in
+km/s, ``m`` = M200 in Msun, ``c`` = NFW concentration). RA/Dec are the usual
+catalogued centres and are not sampled.
+
+Usage::
+
+    from pylgframework import fiducials
+    fiducials.WU
+    fiducials.get("vdm2012")
+"""
+from dataclasses import dataclass, field
+from typing import Dict, Tuple
+
+_LMC = dict(m=1.5e11, c=10.0, ra=80.894, dec=-69.756, mu=18.477,
+            pmra=1910.0, pmdec=229.0, vlos=262.2)
+
+
+@dataclass(frozen=True)
+class Fiducial:
+    name: str
+    obs: Dict[str, Dict[str, float]]
+    reference: str
+    notes: str = ""
+    zero_mass: Tuple[str, ...] = field(default_factory=tuple)   # bodies removed AFTER sampling
+
+    def __repr__(self):
+        return f"Fiducial({self.name!r}, {self.reference})"
+
+
+WU = Fiducial(
+    name="wu2026",
+    reference="Wu, Huang, Zhang, Sun & Shao (2026), ApJ 1001, L19, Table 1, "
+              "doi:10.3847/2041-8213/ae5799 (arXiv:2603.22863)",
+    notes="Follows the framework of Sawala et al. (2025). RA/Dec are the usual catalogued "
+          "centres (McConnachie 2012), NOT taken from the paper table (to be verified).",
+    obs={
+        "MilkyWay": dict(m=1.0e12, c=10.0),
+        "M31": dict(m=1.3e12, c=15.0, ra=10.6847, dec=41.2690, mu=24.407,
+                    pmra=45.9, pmdec=-20.5, vlos=-301.0),
+        "M33": dict(m=3.0e11, c=10.0, ra=23.4621, dec=30.6602, mu=24.670,
+                    pmra=30.6, pmdec=19.0, vlos=-179.2),
+        "LMC": dict(_LMC),
+    })
+
+SAWALA = Fiducial(
+    name="sawala2025",
+    reference="Sawala et al. (2025), Nat. Astron. 9, 1206, doi:10.1038/s41550-025-02563-1 "
+              "(fiducial of the companion notebook)",
+    notes="Masses converted from the 1e10 Msun units of the notebook.",
+    obs={
+        "MilkyWay": dict(m=1.0e12, c=10.0),
+        "M31": dict(m=1.3e12, c=10.0, ra=10.6847, dec=41.2690, mu=24.407,
+                    pmra=48.9, pmdec=-36.9, vlos=-301.0),
+        "M33": dict(m=3.0e11, c=10.0, ra=23.4621, dec=30.6602, mu=24.67,
+                    pmra=31.0, pmdec=-29.0, vlos=-179.2),
+        "LMC": dict(_LMC),
+    })
+
+VDM2019 = Fiducial(
+    name="vdM2019",
+    reference="Sawala et al. (2025) fiducial with the M31 proper motion of "
+              "van der Marel et al. (2019), ApJ 872, 24, doi:10.3847/1538-4357/ab001b",
+    notes="Identical to SAWALA except for the M31 proper motion (49, -38) +- 11 uas/yr, "
+          "the combined Gaia DR2 + HST value of that paper.",
+    obs={
+        "MilkyWay": dict(m=1.0e12, c=10.0),
+        "M31": dict(m=1.3e12, c=10.0, ra=10.6847, dec=41.2690, mu=24.407,
+                    pmra=49.0, pmdec=-38.0, vlos=-301.0),
+        "M33": dict(m=3.0e11, c=10.0, ra=23.4621, dec=30.6602, mu=24.67,
+                    pmra=31.0, pmdec=-29.0, vlos=-179.2),
+        "LMC": dict(_LMC),
+    })
+
+_VDM2012_OBS = {
+    "MilkyWay": dict(m=1.5e12, c=10.0),                      # Paper III canonical model
+    # M31: (v_W, v_N) = (-125.2 +- 30.8, -73.8 +- 28.4) km/s at D = 770 kpc
+    #      -> pmra = +34.3, pmdec = -20.2 uas/yr
+    "M31": dict(m=1.5e12, c=10.0, ra=10.6847, dec=41.2690, mu=24.43,
+                pmra=34.3, pmdec=-20.2, vlos=-301.0),
+    # M33: Paper II Sec. 6.1 Galactocentric velocity -> pmra = +23.2, pmdec = +7.5 uas/yr
+    #      at D = 794 kpc; matches the VLBA maser PM of Brunthaler et al. (2005)
+    "M33": dict(m=1.5e11, c=10.0, ra=23.4621, dec=30.6602, mu=24.50,
+                pmra=23.2, pmdec=7.5, vlos=-180.0),
+    "LMC": dict(_LMC),                                       # NOT in vdM2012 (see notes)
+}
+
+VDM2012 = Fiducial(
+    name="vdm2012",
+    reference="van der Marel et al. (2012), ApJ 753, 8 (doi:10.1088/0004-637X/753/1/8) "
+              "and 9 (doi:10.1088/0004-637X/753/1/9), Papers II and III",
+    notes="Four-body variant. vdM2012 did NOT include the LMC; its entry is inherited "
+          "from WU for comparability.",
+    obs=_VDM2012_OBS)
+
+VDM2012_3B = Fiducial(
+    name="vdm2012_3b",
+    reference="van der Marel et al. (2012), ApJ 753, 8 (doi:10.1088/0004-637X/753/1/8) "
+              "and 9 (doi:10.1088/0004-637X/753/1/9), Papers II and III",
+    notes="Faithful three-body variant (MW+M31+M33). The LMC is sampled (so draws stay "
+          "paired with the other fiducials) and its mass is set to zero afterwards.",
+    obs=_VDM2012_OBS, zero_mass=("LMC",))
+
+ALL = {f.name: f for f in (WU, SAWALA, VDM2019, VDM2012, VDM2012_3B)}
+
+
+def get(name):
+    """Fiducial by name (``wu2026``, ``sawala2025``, ``vdM2019``, ``vdm2012``, ``vdm2012_3b``)."""
+    try:
+        return ALL[name]
+    except KeyError:
+        raise KeyError(f"unknown fiducial {name!r}; available: {sorted(ALL)}") from None

pylgframework/frames.py

@@ -0,0 +1,43 @@
+"""Heliocentric observables <-> Galactocentric phase space (vectorized)."""
+import astropy.units as u
+import numpy as np
+from astropy.coordinates import CartesianDifferential, Galactocentric, ICRS, SkyCoord
+
+from .constants import SUN_R0, SUN_V
+
+
+def galactocentric_frame():
+    return Galactocentric(galcen_distance=SUN_R0 * u.kpc,
+                          galcen_v_sun=CartesianDifferential(list(SUN_V) * (u.km / u.s)))
+
+
+def mu_to_kpc(mu):
+    """Distance modulus -> distance in kpc."""
+    return 10.0 ** ((np.asarray(mu, float) + 5.0) / 5.0) / 1.0e3
+
+
+def helio_to_galactocentric(ra, dec, mu, pmra, pmdec, vlos):
+    """Arrays (or scalars) of heliocentric observables -> position (K,3) kpc, velocity (K,3) km/s.
+
+    ra, dec in deg; mu in mag; pmra (=mu_alpha*) and pmdec in uas/yr; vlos in km/s.
+    """
+    a = lambda x: np.atleast_1d(np.asarray(x, float))
+    c = SkyCoord(ra=a(ra) * u.deg, dec=a(dec) * u.deg, distance=mu_to_kpc(a(mu)) * u.kpc,
+                 pm_ra_cosdec=a(pmra) * u.uas / u.yr, pm_dec=a(pmdec) * u.uas / u.yr,
+                 radial_velocity=a(vlos) * u.km / u.s, frame="icrs")
+    g = c.transform_to(galactocentric_frame())
+    return g.cartesian.xyz.to_value(u.kpc).T, g.velocity.d_xyz.to_value(u.km / u.s).T
+
+
+def galactocentric_to_observables(pos, vel):
+    """Inverse transform: position (kpc) and velocity (km/s) -> dict of heliocentric observables."""
+    pos, vel = np.atleast_2d(pos), np.atleast_2d(vel)
+    c = SkyCoord(x=pos[:, 0] * u.kpc, y=pos[:, 1] * u.kpc, z=pos[:, 2] * u.kpc,
+                 v_x=vel[:, 0] * u.km / u.s, v_y=vel[:, 1] * u.km / u.s, v_z=vel[:, 2] * u.km / u.s,
+                 frame=galactocentric_frame())
+    i = c.transform_to(ICRS())
+    d_pc = i.distance.to_value(u.pc)
+    return dict(ra=i.ra.deg, dec=i.dec.deg, mu=5.0 * np.log10(d_pc) - 5.0,
+                pmra=i.pm_ra_cosdec.to_value(u.uas / u.yr),
+                pmdec=i.pm_dec.to_value(u.uas / u.yr),
+                vlos=i.radial_velocity.to_value(u.km / u.s))

pylgframework/rebound_adapter.py

@@ -0,0 +1,39 @@
+"""Optional adapter for REBOUND simulations (requires ``pip install pylgframework[rebound]``)."""
+import numpy as np
+
+from .constants import KMS, NAMES
+from .frames import galactocentric_to_observables
+
+
+def observables_from_sim(sim, template, names=NAMES, rotation=None):
+    """Heliocentric observables of the particles of a REBOUND simulation at its CURRENT state.
+
+    Call it on the initial state (t = 0): the observables are the present-day values.
+
+    The simulation must use kpc, Msun and Gyr, with the particles ordered as ``names``
+    (particle 0 is the Milky Way). Positions and velocities are taken relative to particle 0,
+    so a simulation moved to its centre of mass (``sim.move_to_com()``) is handled directly.
+    If the simulation axes are rotated with respect to the Galactocentric frame
+    (``x_sim = rotation @ x_galactocentric``), pass that matrix as ``rotation``.
+
+    Masses come from the particles and concentrations from ``template`` (a dict like
+    ``Fiducial.obs``). The result can be passed to ``barycentre(..., sigmas=...)``.
+    Uncertainties are defined on the observables (distance modulus, proper motions, radial
+    velocity), not on Cartesian coordinates, so the correlations of the frame transformation
+    are preserved.
+    """
+    ps = sim.particles
+    pos = np.array([[p.x, p.y, p.z] for p in ps])
+    vel = np.array([[p.vx, p.vy, p.vz] for p in ps]) / KMS          # kpc/Gyr -> km/s
+    pos, vel = pos - pos[0], vel - vel[0]                           # MW at rest at the origin
+    if rotation is not None:
+        R = np.asarray(rotation, float)
+        pos, vel = pos @ R, vel @ R                                 # rows: (R.T @ x) for each x
+    obs = {}
+    ob = galactocentric_to_observables(pos[1:], vel[1:])
+    for j, nm in enumerate(names):
+        d = dict(m=float(ps[j].m), c=float(template[nm]["c"]))
+        if j > 0:
+            d.update({k: float(ob[k][j - 1]) for k in ob})
+        obs[nm] = d
+    return obs

pylgframework/sampling.py

@@ -0,0 +1,46 @@
+"""Truncated-Gaussian sampling of the observables.
+
+The draw scheme is a public contract: realization ``i`` of an ensemble with
+seed ``s`` uses ``numpy.random.default_rng([s, i])`` and consumes the random
+numbers in the order given by the ``sigmas`` dictionary. Changing it breaks
+reproducibility of every published ensemble (and the paired design of
+``compare``).
+"""
+import numpy as np
+
+from .constants import TRUNC
+
+# 1-sigma uncertainties of the 20 observables (Wu et al. 2026, Table 1).
+# Masses in Msun; mu in mag; proper motions in uas/yr; vlos in km/s.
+DEFAULT_SIGMAS = {
+    "MilkyWay": dict(m=2.0e11, c=2.0),
+    "M31": dict(m=4.0e11, c=2.5, mu=0.032, pmra=8.1, pmdec=6.6, vlos=1.0),
+    "M33": dict(m=1.0e11, c=2.0, mu=0.070, pmra=5.7, pmdec=5.7, vlos=1.8),
+    "LMC": dict(m=0.5e11, c=2.0, mu=0.026, pmra=20.0, pmdec=47.0, vlos=3.4),
+}
+
+
+def trunc_normal(rng, mean, sigma, k=TRUNC):
+    """Gaussian truncated at +-k sigma, by rejection."""
+    while True:
+        z = rng.standard_normal()
+        if abs(z) <= k:
+            return float(mean + sigma * z)
+
+
+def sample_obs(rng, base, sigmas=None):
+    """One realization with the same structure as ``base`` (sky positions fixed)."""
+    sigmas = DEFAULT_SIGMAS if sigmas is None else sigmas
+    obs = {}
+    for gal, sig in sigmas.items():
+        obs[gal] = dict(base[gal])
+        for key, s in sig.items():
+            obs[gal][key] = trunc_normal(rng, base[gal][key], s)
+    for gal in base:                      # galaxies without sigmas stay fixed
+        obs.setdefault(gal, dict(base[gal]))
+    return obs
+
+
+def sample_ensemble(base, n, seed, sigmas=None):
+    """List of ``n`` realizations; realization i uses ``default_rng([seed, i])``."""
+    return [sample_obs(np.random.default_rng([seed, i]), base, sigmas) for i in range(n)]

pylgframework-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pylgframework
+Version: 0.1.0
+Summary: Local Group barycentre with propagated observational uncertainty (Monte Carlo)
+Author: Moisés Frutos Plaza
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mfrutosp/pylgframework
+Project-URL: Issues, https://github.com/mfrutosp/pylgframework/issues
+Keywords: Local Group,barycentre,Monte Carlo,astropy,REBOUND
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: astropy>=7.2
+Provides-Extra: rebound
+Requires-Dist: rebound; extra == "rebound"
+Provides-Extra: analysis
+Requires-Dist: scipy; extra == "analysis"
+Requires-Dist: scikit-learn; extra == "analysis"
+Requires-Dist: diptest; extra == "analysis"
+Requires-Dist: matplotlib; extra == "analysis"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: rebound; extra == "test"
+Dynamic: license-file
+
+# pylgframework
+
+A software framework for the Local Group.
+
+The barycentre of the Local Group is routinely adopted as a point estimate. `pylgframework` replaces the
+single-line centre-of-mass calculation with a Monte Carlo that propagates the observational uncertainty of the
+member galaxies, and returns the barycentre together with its uncertainty region.
+
+> Frutos Plaza, M. (2026). *Membership Systematics of the Local Group Barycentre: Uncertainty Region, Dependence
+> on Member Galaxies, and Consistency with the CMB Dipole.* (manuscript; data and code at doi:10.5281/zenodo.23440772)
+
+## Status
+
+[![tests](https://github.com/mfrutosp/pylgframework/actions/workflows/tests.yml/badge.svg)](https://github.com/mfrutosp/pylgframework/actions/workflows/tests.yml)
+
+## Installation
+
+```bash
+pip install -e .                 # core: numpy, pandas, astropy
+pip install -e ".[rebound]"      # adapter for REBOUND simulations
+pip install -e ".[test]"         # development and tests
+```
+
+## Quick start
+
+```python
+from pylgframework import barycentre, compare, fiducials
+
+res = barycentre(fiducials.WU, n=1000, seed=2000)
+print(res)                       # position, velocity, principal axes, CMB-frame speed, assumptions
+
+res.median_position              # kpc, Galactocentric
+res.axes                         # 1-sigma principal axes of the barycentre cloud (kpc)
+res.vcmb("4")                    # speed w.r.t. the CMB (16th, 50th, 84th percentile, km/s)
+res.cloud                        # DataFrame with every realization
+
+# Paired audit of two literature fiducials (identical random draws)
+compare(fiducials.WU, fiducials.VDM2012, n=1000, seed=3000)
+```
+
+Available fiducials: `WU` (Wu et al. 2026), `SAWALA` (Sawala et al. 2025), `VDM2019`, `VDM2012` and
+`VDM2012_3B` (van der Marel et al. 2012, four-body and faithful three-body variants). Each one carries its
+reference and notes (`fiducials.WU.reference`).
+
+Memberships: `"2"` (MW+M31), `"3M"` (+M33), `"3L"` (+LMC), `"4"` (all four).
+
+## Assumptions
+
+* Observables (distance modulus, proper motions, radial velocity, mass) are drawn from Gaussians truncated at
+  ±2σ (the effective standard deviation is about 0.88σ).
+* Sky positions are held fixed; the MW is at rest at the origin of the Galactocentric frame
+  (R0 = 8.122 kpc, v⊙ = (12.9, 245.6, 7.78) km/s).
+* The output is the uncertainty **induced by the declared errors**, not a complete physical uncertainty region.
+* The uncertainty model is fixed across fiducials unless `sigmas=` is supplied.
+
+## Reproducibility
+
+Realization `i` of an ensemble with seed `s` uses `numpy.random.default_rng([s, i])`. This scheme is part of the
+public interface. The test suite reproduces Table 1 and Sects. 3 and 4 of the manuscript:
+
+```bash
+pytest            # fast tests
+```
+
+Verified against the published values (Table 1 of the manuscript) with astropy 7.2.0 (Linux, Python 3.12)
+and astropy 8.0.2 (Linux, Python 3.12; Windows, Python 3.11).
+
+## References
+
+The bibliography of the manuscript, including the sources of every fiducial and of the CMB dipole, is in
+[`docs/references.bib`](docs/references.bib).
+
+## License
+
+MIT.

pylgframework-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pylgframework/__init__.py,sha256=b_GyFWFqtBn_01J_lCb3nG-YJKB0xr3FX51z3qAo858,346
+pylgframework/barycentre.py,sha256=OMDMfyarsyWhtkiqV3TbtRrzGj3hhI4-OIgl9IEVwC8,6819
+pylgframework/compare.py,sha256=0HKvhehOjMZjqJ3BIL6aMw70IYfsUW-X9hE_JwwIPYk,1664
+pylgframework/constants.py,sha256=kr92pj9PpjtsRUmS-gPwtpL2YyjpKzvdc-GwBpknxTs,1273
+pylgframework/fiducials.py,sha256=p6GoVQsRSYx1hFjjqwSWlhDvn5Y9k0SrsTFlJ7OGoIo,4801
+pylgframework/frames.py,sha256=EbsVUr6wMyv7URGkGmGXc3O1Z2RgkPRc4BiHX_1pms8,1992
+pylgframework/rebound_adapter.py,sha256=Zgvqne47MgmJJe1MBthr-lhm8AQy9SckjMRez5qZHJI,1972
+pylgframework/sampling.py,sha256=ORejJu6TcQJxq1UwluW7oUoMkOvXDHeqpU0vH9EpeNM,1803
+pylgframework-0.1.0.dist-info/licenses/LICENSE,sha256=AGTQdZL28K5NA4Ah2hFqxaPVrRyNM1NnDx1VLei_MVo,1098
+pylgframework-0.1.0.dist-info/METADATA,sha256=PD1-EtDLowX9JzYvxxqQZsY54s1SAlvUvZ5hsH8jU9A,4493
+pylgframework-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pylgframework-0.1.0.dist-info/top_level.txt,sha256=6r1J7kRlogLPkNJT7zMNMnTZtP9m115t5F300Uvv9Ao,14
+pylgframework-0.1.0.dist-info/RECORD,,

pylgframework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pylgframework-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moisés Frutos Plaza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pylgframework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pylgframework