Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions src/exozippy/components/component.py
Original file line number Diff line number Diff line change
Expand Up @@ -354,6 +354,100 @@ def _has(key):
wrote[i] = True
return wrote

# The fields that state a posterior term or a support, exactly as
# Parameter._user_constraint_fields defines them -- and deliberately NOT
# `initval`, which is a start value and cannot move a posterior. A star
# whose params file carries only an initval for its radius has said where
# the number is, not that anything should fit it.
USER_CONSTRAINT_FIELDS = ("mu", "sigma", "lower", "upper")

def user_constrained_elements(self, param):
"""Elements whose ``param`` the USER constrained in the params file.

The user-prior half of a readership predicate: a parameter the user
put a prior or a support on is READ, whatever the topology says.
Written for ``Star.structure_consumers`` (review 3.8.1) and shared
with ``Planet.radius_consumers`` (review 2.8.17), so the two cannot
disagree about what counts as a user constraint.

A ``mu``/``sigma`` is a term in the logp -- the user asserting a
spectroscopic measurement -- so it makes the parameter read by
definition, and the element has to stay free for it to apply to.
Five shipped examples do exactly this (kelt17's 7454 +/- 75 K and
[Fe/H] 0.21 +/- 0.08, hd80606, GaiaBH1, HIP1349, kelt4):
deactivating those would DROP a real constraint and stop reporting a
quantity the user measured, which is the opposite of the point. It
is also why readership cannot be answered from the component topology
alone.

``lower``/``upper`` count too, and that is a deliberate widening
rather than an oversight. It is arguable that a bound on a quantity
nothing reads restrains nothing -- but the user has stated an opinion
about this parameter, and the cost of ignoring it is concrete:
``solve_api._bounds_diagnostics`` skips inactive elements, so a bound
that excludes its own initval stopped being reported to the GUI at
all (caught by
``test_solve_api.py::test_bounds_excluding_initval_yields_diagnostic``,
which sets exactly ``star.0.teff: {initval: 6207, lower: 7000}``).
Silently dropping a user's input is the failure mode this whole item
is about; do not narrow this back.

``sigma: 0`` is the ONE exception, and it overrides the rest of the
entry. That is a pin, and the inactive role subsumes it exactly --
the value is held, nothing is sampled, no prior applies -- so
honoring it here would make review 3.8.1's fix a no-op on the very
files it exists for (ob08092 and DC2018_128 pinned all six that way
by hand). Those entries become redundant, and ``build_pymc`` says so
per element.

Read from ``user_params`` (standardized to the index spelling at
ConfigManager construction, i.e. before this runs) and never from the
resolved vectors -- every parameter has bounds and many have a sigma
from defaults.yaml, so a resolved value says nothing about who asked
for it. Most specific spelling wins, as everywhere else: the index
and name forms are checked before the broadcast. Any lookup fault
degrades to "the user wrote nothing", which is the conservative
direction here only in the sense that it matches the old behavior;
it cannot happen for a well-formed params file.
"""

def is_constrained(entry):
sigma = entry.get("sigma")
if isinstance(sigma, (int, float)) and float(sigma) == 0.0:
return False # an explicit pin, which inactive subsumes
return any(f in entry for f in self.USER_CONSTRAINT_FIELDS)

return self.user_entry_elements(param, is_constrained)

def user_entry_elements(self, param, predicate):
"""Elements whose most specific params-file entry satisfies
``predicate``.

The one lookup behind ``user_constrained_elements`` and
``Star.user_pinned_stars``, so the two cannot disagree about which entry
they are reading. Most specific spelling wins, as everywhere else,
which is why this stops at the first hit rather than unioning the
three (contrast ``Parameter._user_constraint_fields``, whose union is
a warning heuristic and does not have to adjudicate).
"""
params = getattr(self.config_manager, "user_params", None) or {}
if not params:
return []
out = []
for i in range(self.n_elements):
keys = [f"{self.prefix}.{i}.{param}"]
if i < len(self.names):
keys.append(f"{self.prefix}.{self.names[i]}.{param}")
keys.append(f"{self.prefix}.{param}")
for key in keys:
entry = user_entry(params, key)
if entry is None:
continue
if predicate(entry):
out.append(i)
break # most specific spelling wins
return out

def direct_angle_requests(self, angle):
"""``(flag, per-element request)`` for an angle with direction latents.

Expand Down
17 changes: 17 additions & 0 deletions src/exozippy/components/orbit/orbit.py
Original file line number Diff line number Diff line change
Expand Up @@ -727,6 +727,23 @@ def inclination_modes(self, system):
_, fitchord = self._resolve_switches(system, log=False)
return self._inc_modes_for(fitchord, system)

def chord_planets(self, system):
"""``{planet index: orbit name}`` for every orbit that SAMPLES the
transit chord, computed without side effects.

A `chord` orbit derives its cos i from its one planet's `p`
(``from_chord``), so that planet's radius is read by the likelihood
whatever else the topology holds. ``Planet.radius_consumers`` asks
this at its own stage 3, which may run before this orbit's; the modes
come from ``inclination_modes`` for the same reason.
"""
planets = self._chord_planet_indices()
return {
int(planets[o]): self.names[o]
for o, mode in enumerate(self.inclination_modes(system))
if mode == "chord"
}

def _parse_ecc_parameterization(self, system=None):
"""Read `fitvcve:`/`fitchord:` into per-orbit mode lists.

Expand Down
108 changes: 108 additions & 0 deletions src/exozippy/components/planet/planet.py
Original file line number Diff line number Diff line change
Expand Up @@ -637,6 +637,114 @@ def register_parameters(self, system):
self._push_rv_mass_hints(system, k_ms_guess)

self._resolve_chen(system)
# After _resolve_chen: the relation is one of the radius's readers.
self._apply_radius_activity(system)

# The planet-local parameters that read `radius` (planet/defaults.yaml):
# a user prior on any of them is a likelihood term in R_P.
RADIUS_READERS = ("radius", "p", "density", "logg")

def radius_consumers(self, system):
"""Per planet: the readers of its radius in this topology.

THE readership predicate for `planet.radius` (review 2.8.17), the
planet's counterpart of ``Star.structure_consumers``: a list, one per
planet, of the labels of what reads it. An empty list means nothing
in the likelihood does, and ``_apply_radius_activity`` makes that
planet's radius INACTIVE.

What counts is a term in the likelihood, not an expression that
merely mentions the radius: `density` and `logg` read it for every
planet always, and nothing reads them back. The complete list, each
entry naming the code that reads it:

* **transit** -- every transit file models every planet's disc
through `p` (transit.py), so any transit block marks every planet.
* **rm** -- an rvinstrument ``rm:`` key: the Rossiter-McLaughlin
kernel reads `p` (rm.py ``compute_rm_rv``). Every planet, the
conservative direction, as for transit.
* **dopptom** -- the Doppler-tomography model reads `p`
(dopptom.py). Every planet.
* **chen** -- the Chen & Kipping (2017) potential is a Gaussian in
R_P (``_add_chen_potential``), on the planets ``_resolve_chen``
enabled. On by default in an RV- or astrometry-only fit, which is
why every RV-only example keeps its radius.
* **orbit chord** -- an orbit sampling the transit chord derives its
cos i from `p` (orbit/defaults.yaml ``from_chord``), so its one
planet's radius is read. Asked of the orbit through the
side-effect-free ``Orbit.chord_planets``, because stage 3 follows
the config key order and the orbit's may not have run.
(A `cosi` orbit REPORTS its chord from `p`, but without
``fitchord`` that mode needs a transit block, which already marked
every planet.)
* **user prior** -- a ``mu``/``sigma``/``lower``/``upper`` on the
radius or on a planet-local quantity derived from it
(``RADIUS_READERS``), with ``sigma: 0`` a pin the inactive role
subsumes (``Component.user_constrained_elements``).

NOT a reader: the base prior (``_add_radius_prior``, uniform in
R_P/R_*). It is the prior OF the radius, and applying it to a
dimension nothing else reads is exactly the dead, prior-only
dimension this predicate exists to remove. Microlensing reads the
planet's MASS (through q), never its radius.
"""
from ..rm import rm_enabled

out = [[] for _ in range(self.n_elements)]
everyone = []
if in_topology(system, "transit") is not None:
everyone.append("transit")
if rm_enabled(system):
everyone.append("rm")
if in_topology(system, "dopptom") is not None:
everyone.append("dopptom")
for labels in out:
labels.extend(everyone)

for i, on in enumerate(self.chen):
if on:
out[i].append("chen")

orbit = system.active_components.get("orbit")
if orbit is not None:
for i, o_name in orbit.chord_planets(system).items():
out[i].append(f"orbit {o_name} (fitchord)")

for param in self.RADIUS_READERS:
for i in self.user_constrained_elements(param):
out[i].append(f"user prior on {param}")
return out

def _apply_radius_activity(self, system):
"""Make `radius` INACTIVE on the planets nothing reads it for.

A microlensing planet (review 2.8.17) is the case: the lens reads its
mass through q, nothing reads its radius, and a free radius was one
sampled dimension refilling its prior plus R_P, rho_P and log g_P
table rows that were pure prior. The treatment is
``Star._apply_structure_activity``'s, and for the same reason the
radius stays DECLARED (wholly inactive) rather than dropped:
`density`, `logg` and -- with an orbit -- `p` name it in their deps,
and everything that derives from it (those three, then the transit
durations and probabilities through `p`) inherits the role through
``Component._inherit_inactivity``. Inactive means no raw
coordinate, no prior or potential, no table row, no trace report.
"""
active = [bool(c) for c in self.radius_consumers(system)]
if all(active):
return
self.manifest["radius"] = merge_options(
self.manifest["radius"], mask=active
)
names = ", ".join(n for n, on in zip(self.names, active) if not on)
logger.debug(
f"{self.log_tag()} nothing in this topology reads the radius of "
f"{names}, so it is not a parameter of this fit: held at its "
f"resolved value, sampled by nothing and not reported (nor is "
f"anything derived from it). A transit, RM or Doppler-tomography "
f"data set, the Chen & Kipping relation, 'fitchord: true' on its "
f"orbit or a params prior on the radius makes it free."
)

# The keys that state a planet's mass, in any of its coordinates. A user
# value on one of them and RVInstrument's semi-amplitude estimate are two
Expand Down
13 changes: 12 additions & 1 deletion src/exozippy/components/star/star.md
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,18 @@ Tests: `tests/test_fitmsini.py`.
- **The term.** `Planet.build_likelihood` adds `planet.radius_jacobian = -sum log R_*` over the planets below, R_* being each planet's host through `star_map`, so the implied prior is uniform in (p, R_*). JDE 2026-10-16: match EXOFASTv2 for now; whether a prior uniform in log R_P would be more physical is open. The choice lives in ONE place, `planet/physics.py` `radius_base_prior_logp` (the log-density of the base prior relative to uniform in R_P), plus the Prior-column and prose strings declared beside the call; swapping the base prior is a change there.
- **Which planets.** Every planet whose `radius` element is SAMPLED (`Parameter.element_is_sampled`), and only when an orbit exists (p and everything that reads R_P/R_* exist only then). A pinned radius (`sigma: 0`, including a hard link) gets nothing: the term would be a function of R_* alone, a prior on the star.
- **Other radius priors multiply it.** A user `mu`/`sigma` on R_P and the Chen & Kipping relation are separate potentials on R_P; they compose with the flat-in-p base prior exactly as EXOFASTv2 applies both as penalties on its derived rp, so the Jacobian stays. The Prior column reports the user's Gaussian and the `$\propto 1/R_*$` term together.
- **The bounds are still on R_P, not on p.** Where nothing constrains R_P (no transit, chen off, no user prior), the 1/R_* factor integrated over the fixed R_P interval is a 1/R_* prior on the host, which EXOFASTv2's p-bounded stepping does not have. Such a radius measures nothing. With chen on (an RV- or astrometry-only fit) EXOFASTv2 carries the same 1/R_* marginal, because the relation fixes R_P = p R_* at a mass-given value.
- **The bounds are still on R_P, not on p.** Where nothing constrains R_P (no transit, chen off, no user prior), the 1/R_* factor integrated over the fixed R_P interval would be a 1/R_* prior on the host, which EXOFASTv2's p-bounded stepping does not have -- but such a radius is now INACTIVE (next section), so it is not sampled and gets no term. With chen on (an RV- or astrometry-only fit) EXOFASTv2 carries the same 1/R_* marginal, because the relation fixes R_P = p R_* at a mass-given value.
- **R_* is floored strictly positive inside the log** (`physics.STAR_RADIUS_LOG_FLOOR`, the CLAUDE.md where-trap rule): `star.radius` defaults to `[0.1, 2000]` solRad, but a user may widen it to 0 or drop the bound for a Gaussian.

Tests: `tests/test_radius_prior.py` -- carried from the raw coordinates to (p, R_*) through the model's own transform, the no-likelihood density is flat to 1e-6, and with the term removed it is off by exactly `+log R_*`.

## Which planets have a radius (`Planet.radius_consumers`, review 2.8.17)

`planet.radius` is a parameter of a fit only where something in the likelihood reads it; elsewhere it is INACTIVE (no raw coordinate, no prior or potential, no table row), exactly the tier-1 treatment "Which stellar structure parameters a topology actually has" gives a star's radius. The case it exists for is the microlensing planet: the lens reads the planet's MASS (through q) and nothing reads its radius, so a free radius was a sampled dimension refilling its prior plus R_P, rho_P and log g_P rows that were pure prior.

- **The readers**, one predicate (`Planet.radius_consumers`), each naming the code that reads: a `transit` block (every transit file models every planet's disc through `p`), an rvinstrument `rm:` key (the RM kernel reads `p`), `dopptom` (reads `p`) -- those three mark every planet -- the Chen & Kipping relation on that planet (`_resolve_chen`; on by default in an RV- or astrometry-only fit, so those keep their radius), an orbit SAMPLING the transit chord (`fitchord`: cos i derives from `p`; asked through `Orbit.chord_planets`, because the orbit's stage 3 may run after the planet's), and a user `mu`/`sigma`/`lower`/`upper` on `radius`, `p`, `density` or `logg` (`Component.user_constrained_elements`, the rule Star uses, so `sigma: 0` is a pin the inactive role subsumes and an `initval` alone is not a reader).
- **Not a reader: the base prior above.** It is the prior OF the radius; counting it would make the predicate true everywhere.
- **Declared, not dropped.** `density`, `logg` and, with an orbit, `p` name `radius` in their deps, so the radius stays in the manifest, masked; everything derived from it (those, and through `p` the transit durations, `b`, `delta` and the transit probabilities) inherits the role through `Component._inherit_inactivity` and is not reported. The same reason Star keeps its unread radius declared.
- **Blast radius, measured over every shipped config:** only the microlensing configs with a planet (DC2018_128 and its `DC2018/configs` variants, KMT-2019-BLG-1806, kb180087_obj3, MOA-2008-BLG-379, ob170114, OGLE_0383LD) and `examples/HD114762` (an astrometric stellar companion with `chen: false`) change; every transit, RV and astrometry-with-chen example declares the radius exactly as before. All of the changed ones except ob170114 pinned the radius by hand (`sigma: 0`), which is now redundant.

Tests: `tests/test_planet_radius_activity.py`.
Loading
Loading