pylgframework 0.1.0__tar.gz

pylgframework-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,75 @@
+# 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/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pylgframework"
+version = "0.1.0"
+description = "Local Group barycentre with propagated observational uncertainty (Monte Carlo)"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Moisés Frutos Plaza" }]
+keywords = ["Local Group", "barycentre", "Monte Carlo", "astropy", "REBOUND"]
+dependencies = ["numpy", "pandas", "astropy>=7.2"]
+
+[project.urls]
+Homepage = "https://github.com/mfrutosp/pylgframework"
+Issues = "https://github.com/mfrutosp/pylgframework/issues"
+
+[project.optional-dependencies]
+rebound = ["rebound"]
+analysis = ["scipy", "scikit-learn", "diptest", "matplotlib"]
+test = ["pytest", "rebound"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = ["slow: reproduces published values with N = 1000 (seconds to a minute)"]
+testpaths = ["tests"]

pylgframework-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pylgframework-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/pylgframework.egg-info/PKG-INFO

@@ -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/src/pylgframework.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/pylgframework/__init__.py
+src/pylgframework/barycentre.py
+src/pylgframework/compare.py
+src/pylgframework/constants.py
+src/pylgframework/fiducials.py
+src/pylgframework/frames.py
+src/pylgframework/rebound_adapter.py
+src/pylgframework/sampling.py
+src/pylgframework.egg-info/PKG-INFO
+src/pylgframework.egg-info/SOURCES.txt
+src/pylgframework.egg-info/dependency_links.txt
+src/pylgframework.egg-info/requires.txt
+src/pylgframework.egg-info/top_level.txt
+tests/test_core.py
+tests/test_paper_values.py
+tests/test_rebound_adapter.py
+tests/test_rebound_simulation.py

pylgframework-0.1.0/src/pylgframework.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pylgframework-0.1.0/src/pylgframework.egg-info/requires.txt

@@ -0,0 +1,16 @@
+numpy
+pandas
+astropy>=7.2
+
+[analysis]
+scipy
+scikit-learn
+diptest
+matplotlib
+
+[rebound]
+rebound
+
+[test]
+pytest
+rebound

pylgframework-0.1.0/src/pylgframework.egg-info/top_level.txt

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

pylgframework-0.1.0/tests/test_core.py

@@ -0,0 +1,68 @@
+import numpy as np
+import pytest
+
+from pylgframework import barycentre, compare, fiducials
+from pylgframework.frames import galactocentric_to_observables, helio_to_galactocentric
+from pylgframework.sampling import sample_ensemble
+
+
+def test_realizations_are_reproducible_one_by_one():
+    a = sample_ensemble(fiducials.WU.obs, 5, seed=7)
+    b = sample_ensemble(fiducials.WU.obs, 8, seed=7)
+    assert a == b[:5]                      # realization i depends only on (seed, i)
+
+
+def test_truncation_is_respected():
+    base = fiducials.WU.obs
+    from pylgframework.sampling import DEFAULT_SIGMAS
+    for o in sample_ensemble(base, 200, seed=1):
+        for g, sig in DEFAULT_SIGMAS.items():
+            for k, s in sig.items():
+                assert abs(o[g][k] - base[g][k]) <= 2.0 * s + 1e-9
+
+
+def test_sky_positions_are_fixed():
+    base = fiducials.WU.obs
+    for o in sample_ensemble(base, 20, seed=1):
+        for g in ("M31", "M33", "LMC"):
+            assert o[g]["ra"] == base[g]["ra"] and o[g]["dec"] == base[g]["dec"]
+
+
+def test_transform_roundtrip():
+    o = fiducials.WU.obs["M31"]
+    r, v = helio_to_galactocentric(o["ra"], o["dec"], o["mu"], o["pmra"], o["pmdec"], o["vlos"])
+    back = galactocentric_to_observables(r, v)
+    for k in ("ra", "dec", "mu", "pmra", "pmdec", "vlos"):
+        assert back[k][0] == pytest.approx(o[k], rel=1e-6, abs=1e-6)
+
+
+def test_three_body_variant_degenerates_exactly():
+    c = barycentre("vdm2012_3b", n=50, seed=3000).cloud
+    assert (c.shift_LMC_kpc == 0).all() and (c.dv_LMC_kms == 0).all()
+    np.testing.assert_allclose(c.shift_2to4_kpc, c.shift_M33_kpc)
+    np.testing.assert_allclose(c.vcmb_4_kms, c.vcmb_3M_kms)
+
+
+def test_paired_comparison_uses_identical_draws():
+    # Same fiducial against itself: zero offset, zero velocity difference.
+    c = compare(fiducials.WU, fiducials.WU, n=50, seed=3000)
+    assert c.offset_kpc == pytest.approx(0.0, abs=1e-9)
+    assert all(abs(v) < 1e-9 for v in c.dvcmb.values())
+
+
+def test_custom_sigmas_change_the_cloud():
+    from pylgframework import DEFAULT_SIGMAS
+    tight = {g: {k: v / 10 for k, v in s.items()} for g, s in DEFAULT_SIGMAS.items()}
+    a = barycentre(fiducials.WU, n=200, seed=1)
+    b = barycentre(fiducials.WU, n=200, seed=1, sigmas=tight)
+    assert b.axes[0] < 0.2 * a.axes[0]
+
+
+def test_summary_states_the_assumptions():
+    s = barycentre(fiducials.WU, n=20, seed=1).summary()
+    assert "truncated" in s and "INDUCED" in s
+
+
+def test_unknown_fiducial():
+    with pytest.raises(KeyError):
+        fiducials.get("nope")

pylgframework-0.1.0/tests/test_paper_values.py

@@ -0,0 +1,52 @@
+"""Regression against the values published in Frutos Plaza (2026), Table 1 and Sect. 3.
+
+Tolerances reflect the rounding of the published numbers (and astropy version differences).
+"""
+import numpy as np
+import pytest
+
+from pylgframework import barycentre, compare, fiducials
+
+pytestmark = pytest.mark.slow
+
+# fiducial: (a1, a2, a3, D_BC, RA, Dec, vCMB(2), vCMB(4), Delta_2to4)   [Table 1, seed 3000]
+TABLE1 = {
+    "wu2026":     (53.6, 7.3, 0.2, 448, 13.4, 38.8, 621, 629, 34),
+    "sawala2025": (53.6, 7.3, 0.2, 448, 13.4, 38.8, 619, 627, 34),
+    "vdM2019":    (53.6, 7.3, 0.2, 448, 13.4, 38.8, 619, 626, 34),
+    "vdm2012":    (48.8, 5.3, 0.2, 381, 11.6, 39.9, 604, 614, 15),
+    "vdm2012_3b": (49.6, 5.5, 0.0, 401, 11.4, 40.2, 604, 602, 21),
+}
+
+
+@pytest.mark.parametrize("name", sorted(TABLE1))
+def test_table1(name):
+    a1, a2, a3, d, ra, dec, v2, v4, d24 = TABLE1[name]
+    r = barycentre(name, n=1000, seed=3000)
+    c = r.cloud
+    np.testing.assert_allclose(r.axes, [a1, a2, a3], atol=0.15)
+    assert abs(c.bc0_dist.median() - d) < 1.0
+    assert abs(c.bc0_ra.median() - ra) < 0.1
+    assert abs(c.bc0_dec.median() - dec) < 0.1
+    assert abs(c.vcmb_2_kms.median() - v2) < 1.0
+    assert abs(c.vcmb_4_kms.median() - v4) < 1.0
+    assert abs(c.shift_2to4_kpc.median() - d24) < 1.0
+
+
+def test_main_text_ensemble():
+    """Sect. 3.1 and 3.3 (seed 2000)."""
+    r = barycentre(fiducials.WU, n=1000, seed=2000)
+    np.testing.assert_allclose(r.axes, [54.8, 7.7, 0.2], atol=0.15)
+    assert abs(np.linalg.norm(r.median_position) - 452) < 1.5
+    assert abs(r.cloud.vcmb_2_kms.median() - 622) < 1.0
+    assert abs(r.cloud.vcmb_4_kms.median() - 630) < 1.0
+    assert abs(r.cloud.shift_M33_kpc.median() - 53) < 1.0
+    assert abs(r.cloud.shift_LMC_kpc.median() - 27) < 1.0
+
+
+def test_fiducial_audit():
+    """Sect. 4: 68 kpc (1.2 sigma) and 17 km/s between the modern and the HST-era fiducial."""
+    c = compare(fiducials.WU, fiducials.VDM2012, n=1000, seed=3000)
+    assert abs(c.offset_kpc - 67.8) < 0.5
+    assert abs(c.offset_sigma - 1.2) < 0.1
+    assert abs(c.dvcmb["2"] + 17) < 1.0

pylgframework-0.1.0/tests/test_rebound_adapter.py

@@ -0,0 +1,24 @@
+import numpy as np
+import pytest
+
+rebound = pytest.importorskip("rebound")
+
+from pylgframework import barycentre, fiducials
+from pylgframework.constants import KMS, NAMES
+from pylgframework.barycentre import phase_space
+from pylgframework.rebound_adapter import observables_from_sim
+
+
+def test_sim_roundtrip_reproduces_the_nominal_barycentre():
+    base = fiducials.WU.obs
+    m, r, v = phase_space([base])
+    sim = rebound.Simulation()
+    sim.G = 4.30091727e-6 * KMS**2          # kpc^3 / (Msun Gyr^2); the adapter only reads state
+    for j in range(4):
+        sim.add(m=m[0, j], x=r[0, j, 0], y=r[0, j, 1], z=r[0, j, 2],
+                vx=v[0, j, 0] * KMS, vy=v[0, j, 1] * KMS, vz=v[0, j, 2] * KMS)
+    obs = observables_from_sim(sim, base)
+    a = barycentre(base, n=1, seed=0, sigmas={})
+    b = barycentre(obs, n=1, seed=0, sigmas={})
+    np.testing.assert_allclose(b.nominal_position, a.nominal_position, atol=1e-3)
+    np.testing.assert_allclose(b.nominal_velocity, a.nominal_velocity, atol=1e-3)

pylgframework-0.1.0/tests/test_rebound_simulation.py

@@ -0,0 +1,88 @@
+"""REBOUND simulation of the Local Group used as a worked example of ``pylgframework``.
+
+The simulation is built as in the dynamical code of the manuscript (IAS15, G in
+kpc^3 Msun^-1 Gyr^-2, four bodies MW, M31, M33, LMC, 5 kpc softening, moved to the centre of
+mass), without dynamical friction or mass transfer, which are not part of this package.
+
+Usage pattern::
+
+    sim = build_local_group_sim(fiducials.WU)          # your own REBOUND simulation
+    obs = observables_from_sim(sim, fiducials.WU.obs)  # recover the heliocentric observables
+    res = barycentre(obs, n=1000, seed=2000)           # barycentre with its uncertainty
+    print(res)                                         # replaces sim.com()
+"""
+import numpy as np
+import pytest
+
+rebound = pytest.importorskip("rebound")
+
+from pylgframework import barycentre, fiducials
+from pylgframework.barycentre import phase_space
+from pylgframework.constants import KMS, NAMES
+from pylgframework.rebound_adapter import observables_from_sim
+
+G = 4.30091727e-6 * KMS**2          # kpc^3 / (Msun Gyr^2)
+SOFTENING = 5.0                      # kpc
+
+
+def build_local_group_sim(fiducial, rotation=None):
+    """Four-body Local Group simulation from a fiducial, in the barycentric frame."""
+    m, r, v = phase_space([fiducial.obs], fiducial.zero_mass)
+    sim = rebound.Simulation()
+    sim.integrator = "ias15"
+    sim.G = G
+    sim.softening = SOFTENING
+    sim.collision = "none"
+    for j, name in enumerate(NAMES):
+        rj, vj = r[0, j], v[0, j] * KMS                          # km/s -> kpc/Gyr
+        if rotation is not None:
+            rj, vj = rotation @ rj, rotation @ vj
+        sim.add(m=m[0, j], x=rj[0], y=rj[1], z=rj[2], vx=vj[0], vy=vj[1], vz=vj[2], name=name)
+    sim.move_to_com()
+    return sim
+
+
+@pytest.fixture
+def sim():
+    return build_local_group_sim(fiducials.WU)
+
+
+def test_simulation_is_in_the_barycentric_frame(sim):
+    com = sim.com()
+    assert np.linalg.norm([com.x, com.y, com.z]) < 1e-9
+    assert np.linalg.norm([com.vx, com.vy, com.vz]) < 1e-9
+
+
+def test_adapter_recovers_the_nominal_barycentre(sim):
+    """sim.com() is a point; the adapter + barycentre() gives the same point, with uncertainty."""
+    obs = observables_from_sim(sim, fiducials.WU.obs)
+    res = barycentre(obs, n=1, seed=0, sigmas={})
+    ref = barycentre(fiducials.WU, n=1, seed=0, sigmas={})
+    np.testing.assert_allclose(res.nominal_position, ref.nominal_position, atol=1e-3)
+    np.testing.assert_allclose(res.nominal_velocity, ref.nominal_velocity, atol=1e-3)
+
+
+def test_uncertainty_from_the_simulation_matches_the_fiducial(sim):
+    obs = observables_from_sim(sim, fiducials.WU.obs)
+    a = barycentre(obs, n=300, seed=2000)
+    b = barycentre(fiducials.WU, n=300, seed=2000)
+    np.testing.assert_allclose(a.median_position, b.median_position, atol=0.05)
+    np.testing.assert_allclose(a.axes, b.axes, atol=0.05)
+
+
+def test_rotated_simulation_axes_are_handled():
+    th = np.deg2rad(37.0)
+    R = np.array([[np.cos(th), -np.sin(th), 0.0], [np.sin(th), np.cos(th), 0.0], [0.0, 0.0, 1.0]])
+    sim_r = build_local_group_sim(fiducials.WU, rotation=R)
+    obs = observables_from_sim(sim_r, fiducials.WU.obs, rotation=R)
+    res = barycentre(obs, n=1, seed=0, sigmas={})
+    ref = barycentre(fiducials.WU, n=1, seed=0, sigmas={})
+    np.testing.assert_allclose(res.nominal_position, ref.nominal_position, atol=1e-3)
+
+
+def test_centre_of_mass_is_ballistic_during_integration(sim):
+    """Internal forces conserve momentum: the barycentre stays at the origin (bookkeeping check)."""
+    sim.integrate(2.0)
+    com = sim.com()
+    assert np.linalg.norm([com.x, com.y, com.z]) < 1e-6
+    assert np.linalg.norm([com.vx, com.vy, com.vz]) < 1e-6