From a93e41f75cf2a6f62dadd43978a416532f9a6185 Mon Sep 17 00:00:00 2001 From: Richard O'Shaughnessy Date: Sat, 5 Sep 2026 13:06:52 -0400 Subject: [PATCH] Prepare 0.0.18.0rc3 release notes and version --- CHANGES.rst | 270 ++++------------------------------------------------ setup.py | 2 +- 2 files changed, 17 insertions(+), 255 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 1745cd2c7..ab383a7b6 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,259 +1,21 @@ - 0.0.18.0 ------------ -development tree is rift_O4d. - -** BEHAVIOUR CHANGE, jax ILE: flow re-use across ``--n-events-to-analyze`` is now - OFF by default. ``--flow-reuse`` restores the old behaviour; ``--no-flow-reuse`` - is kept and now restates the default, so existing command lines keep working. - Measured over an 8-event batch at two seeds: re-using the trained flow contracts - the extrinsic posterior monotonically in slot index -- psi to ~40% of its - no-re-use width by slot 7, on BOTH seeds, with slot 0 (where no re-use has yet - happened) at ~1.0 as a control -- while costing no measurable wall time (1589 s - mean with re-use, 1567 s without; the seed-to-seed spread is larger than the - difference and its sign flips). Anyone relying on re-use to amortize a batch - must now pass ``--flow-reuse`` explicitly, and should not do so for any run whose - extrinsic SAMPLES are used. Evidence is less affected than samples. - -** jax ILE ``--save-samples`` is now a FAIR DRAW. Previously the driver wrote - whatever cloud the sampler produced, with no weight column, so every consumer - read a Gaussian-proposal cloud (``--mode laplace-is``, the default) or raw - PRIOR draws (``--mode prior-mc``) as if it were a posterior. Each estimator - now returns its per-sample importance weight and the export is - multinomial-resampled against it, matching production ILE's convention - (``RIFT/integrators/mcsampler.py::integrate``). The data columns and their - header line are unchanged for a given ``--mode``; a second header line now - records the mode and the export ESS. ``--fairdraw-extrinsic-output``, - ``--fairdraw-extrinsic-output-n-max`` and ``--n-fairdraw-extrinsic-samples`` - are implemented (gated per mode, and honoured as a COUNT contract even when - the weights are uniform). The requested count is clamped ONLY by the rows - available; those already carry ILE's ``1.5*ESS`` cap wherever the export - weights were non-uniform, applied against the EXPORT weights. There is - deliberately no second clamp by the evidence estimator's ``neff``: on the - flowMC modes and on ``laplace-is`` that number describes a separate cloud - (the moment-matched Gaussian evidence proposal, or the annealing ladder's - minimum rung ESS), and clamping by it truncated valid equal-weight chains. NOTE ``--fairdraw-extrinsic-output-n-max`` - defaults to 5, as in ILE, so passing ``--fairdraw-extrinsic-output`` without - an explicit maximum now yields 5 rows where it previously yielded the whole - cloud. If the weights admit no fair draw at all (degenerate or - unnormalizable), the driver writes NO ``*_samples.dat`` -- and deletes a stale - one at that path -- and fails the event (``--soft-fail-event-range`` still - skips to the next one) rather than exporting an unreweighted cloud under the - name that means "posterior draws". That check runs BEFORE the - ``__.dat`` result row is written, so such an event leaves no - normal ILE result behind either (a stale row is likewise removed); otherwise a - soft-failed, collapsed integration was still collectable as a success. - - (rc0) O4d base refresh, from rift_O4c to rift_O4d: Python/numpy CI modernization (py3.10-py3.13, - numpy 2.x checks), Asimov/RIFT smoke tests, docs deployment, pluggable workflow backends and - simulation-manager prototypes, distance-grid/distance-slice likelihood export, container-family and pixi/SWIG - canaries, hyperpipeline ASCII workflow support, parsimonious-placement preview, EFPE and standalone NR-frame - utilities, plot_RIFT diagnostics, and GPU/CuPy portability fixes. - -** (rc1) - - parsimonious-placement (preview): new RIFT.misc.tracer_placement engine (SMC+MALA, birth-death, - and SMC-MALA+BD samplers; pluggable RF / RBF / polynomial / quadratic fits) plus two - opt-in CLI tools that mirror the existing puffball tools' I/O contract: - util_HyperparameterTracerUpdate.py (hyperpipe drop-in for util_HyperparameterPuffball.py) - and util_ParameterTracerUpdate.py (event-level drop-in for util_ParameterPuffball.py). - Default behavior preserves the existing pipelines (the new tools are not invoked unless - the user points --puff-exe at them); both also accept --update-method puffball as an - exact-regression fallback. See - https://git.ligo.org/rapidpe-rift/rift/-/merge_requests/ (TBD) and the project notes at - 20260513-Me-ParsimoniousPlacementOptions/parsimonious_placement_plan.md. - - **CHANGES lnL VALUES** (issue #146) time-marginalization window grid: the two extrinsic ILE - drivers built different grids. bin/integrate_likelihood_extrinsic_batchmode used - linspace(-iwh, iwh, int(2*iwh/deltaT)) at ten sites; RIFT.likelihood.jax_ile (and so - bin/integrate_likelihood_extrinsic_jax) used arange(-Nw, Nw)*deltaT. Both likelihoods consume - only tvals[0] and len(tvals) -- each steps by deltaT and integrates with dx=deltaT -- so the - grids differed in origin by 0.2 samples, enough to round ifirst to a different integer sample - per detector, and in length at srate 1024/2048/16384. Both now call the single constructor - factored_likelihood.marginalization_time_grid(iwh, deltaT), spaced exactly deltaT with - npts = int(2*iwh/deltaT). Batchmode's window LENGTH is unchanged at every sample rate; its - grid ORIGIN moves by +4.88e-5 s, which shifts lnL by up to ~0.5 nats at the injected - parameters at srate 4096 (less at 16384). Marginalized lnZ moves sub-nat. Anyone comparing - against archived runs should expect a shift at that scale. The JAX driver's window gains one - sample at srate 1024/2048/16384; measured effect on its lnL is < 4e-3 nats. - - generic worfklow backend (condor, slurm, htcondor, etc) via dag_utils_generic - - simulation_manager framework: interface requirements for external adaptive simulations - - CIP hyperpipe improvements (initialize_me; enable population and EOS params in using_eos file with arbitrary - labelled parameters; arbitrary coordinates); CIP xgboost gp fit (from Aasim); install make 'precession' optional; see also 0.0.17.4rc0 - igwn-ligolw. Hyperpipe 'omegaconf/hydra' framework - - parsimonious placement (preview): new RIFT.misc.tracer_placement engine package (SMC+MALA / birth-death / - SMC-MALA+BD samplers with pluggable RF / RBF / polynomial / quadratic surrogate fits) plus two thin - command-line drivers, bin/util_HyperparameterTracerUpdate.py (hyperpipe, .dat I/O) and - bin/util_ParameterTracerUpdate.py (event-level, XML I/O via lalsimutils). Both are drop-in alternatives to - util_HyperparameterPuffball.py / util_ParameterPuffball.py: legacy default behavior is unchanged --- the new - tools are only invoked when --puff-exe points at them. create_eos_posterior_pipeline gains - --tracer-only-marg and --tracer-final-marg-iterations to optionally skip MARG_* (posterior) nodes in - intermediate iterations and rely on MARG_PUFF (placement) jobs alone, recovering MARG only for the final N - iterations. util_RIFT_hyperpipe.py forwards the same flags via arch.tracer-only-marg / - arch.tracer-final-marg-iterations and exposes a puff.settings: block mirroring post.settings: so tracer - sampler hyperparameters can be set declaratively in Hydra. See - 20260513-Me-ParsimoniousPlacementOptions/parsimonious_placement_plan.md for theory, prototype results, - rollout plan, and references. - - distance grid creation and (AD-compatible) fit - - RiftFloat wrapper for portability across platforms with modern python/numpy - - ascii data format; waveforms (epfe); container auto-selection framework ; cepp_alternate now feature-parity; - mcsamplerEnsemble full GPU path - - demos: calmarg, lisa, distance grids, likelihood export, multiple GPU use, hyperpipe - - tools: importing cal posteriors from other codes - - (rc1 pending) In-loop calibration marginalization: move calibration draws into ILE, add loop and fused - GPU kernels (including distance-marginalized and phase-marginalized paths), export cal/time diagnostics, - account for calibration Monte-Carlo error in reported uncertainty, add adaptive/pilot calibration proposal - scaffolding, and include a runnable calmarg demo with OSG/container transfer fixes. - - (rc1 pending) Extrinsic proposal handoff and sampler robustness: save and consolidate extrinsic GMM - breadcrumbs across iterations, seed later ILE jobs from those proposals, add GMM proposal/adaptation - controls and diagnostics, improve log-domain covariance/ESS handling, and thread the cal/extrinsic seed - barriers through CEPP/puffball workflows. - - Likelihood export Differentiable JAX likelihood/export work: optional jax_gp interpolators, differentiable - export artifacts, quad-GP and RF/GP validation tooling, jax_cip experiments - - JAX ILE driver with AD-compatible extrinsic likelihood, distance/phase marginalization, network coordinates, and gradient-aware - samplers. These remain optional extras and are skipped by base CI when JAX is not installed. - - LISA support: add a LISA compatibility layer, response import path, standalone helper - contract, LISA ILE scaffold, and synthetic operational/import tests. - - EOS/coordinate and workflow updates: add NMB/PCA/tabular EOS sequence dispatch and - single-EOS-index evidence support, coordinate-plugin hooks for posterior plotting and puffing, Morisaki-frame - and aligned-spin coordinate helpers for GP/JAX studies, container-universe/OSDF scitokens support, and - per-machine container image selection. - - ILE 'fanout' submission can use multiple GPUs on one host (RIFT_ILE_GPU_FANOUT) - - Qlm interpolated in factored_likelihood...NoLoop (option) - -** (rc2) - Development tree is rift_O4d, staged on oshaughnessy-junior/rift_O4d. The per-feature detail, review - history, and measurements live in fork PRs #19-#84 of oshaughnessy-junior/research-projects-RIT; the - grouping below is by subsystem, not by merge order. Every item is default-off or behavior-preserving - unless it is described as a bug fix. - - extrinsic sampler PORTFOLIO (mcsamplerPortfolio): member realizations, so cold AV/GMM members no - longer crash on their first draw; balance-heuristic (q_mix) estimator, which makes the portfolio safe - when one member's proposal is wrong; VARAHA never-freeze default plus a freeze-policy CLI and a draw-share - band (--portfolio-varaha-max-frac); opt-in truncated-IS weight clipping restricted to the ADAPTATION / - proposal-fit stream only, with the clipped mass tracked (unbiased by construction); opt-in adaptive draw - allocation driven by marginal pooled n_eff or q_mix-native MIS credit; per-member interval narrowing - (restrict_member_range); warm-startable members with setup-arg snapshot/replay; explicit full-support - declaration; fair-draw export weights built on the sampler's own backend rather than forced to host. - - ADAPTIVE VOLUME sampler (mcsamplerAdaptiveVolume): bootstrappable warm start from samples / Fisher / - mixture / saved state, with a coverage floor (cover_frac) for cross-problem reuse; vectorized - sample_from_bins (unblocks concentrated warm starts); opt-in anisotropic per-axis bin allocation - (--sampler-anisotropic-bins); draw_simplified subsamples randomly instead of head-slicing a bin-ordered - cloud; integrand fed on its native backend (fixes a real GPU-ILE regression). Bug fixes: the high-SNR - empty-live-volume crash, the empty-selection crash in update_sampling_prior_selfish, and bootstrap bin - indices out of range on wide seeds. Sampler collapse is now machine-readable, aggregated across - replicas, and the rejection gate is applied to the POOLED verdict too. - - high-SNR rescue and warm start in ILE: L0 auto-rescue plus L1 sequential warm start, with the warm seed - judged by RANK and puffed to the measured posterior scale, seeded from the points the pass RETAINED - (not the fair-draw subset), and a warm-seed reserve that records the exact pre-cap weight total; the - warm pass is rejected on evidence only. ProposalField scaffold and a cherry-picked-pilot workflow for - L3 iteration-to-iteration proposal reuse. Also fixes a pre-existing mcsamplerEnsemble cold-start crash. - - GMM proposals: data-driven ("flexible") component allocation with warm-start survival; O(k^3) Hungarian - component matching, replacing an O(k!) permutation search; bootstrap_from_samples for warm-starting from - a seed cloud; an OPT-IN defensive component whose coverage guarantee is verified and held through the - sampler lifecycle rather than only at setup; invalid n_comp now warns instead of silently never training; - a CUDA device probe before selecting cupy, and a loud failure when a GMM refit never succeeds. - - Monte-Carlo error and evidence integrity: mcsamplerGPU adaptive-proposal support truncation, which - biased lnZ LOW, is fixed; the MC error estimate is stabilized (Pareto k-hat tail diagnostic, cold - replicas, disclosed budgets) and replicas are pooled for export with the cached log_weights rebuilt so - the science exports use the corrected weights; _rvs importance weights are derived rather than read from - the ambiguous log_weights cache; the lnL/log-representation convention is keyed off the stored - representation, fixing --internal-use-lnL and the distance-grid export; marginal log-likelihood now uses - all available values (upstream contribution, C. Talbot). - - in-loop CALIBRATION MARGINALIZATION: fused-kernel self-term fix -- the per-realization - rho_sq_c = is now formed per calibration draw instead of sharing one cal-independent - norm, with --calibration-global-norm to fall back to the cheaper route; graceful fallback to the - prior when a cal proposal seed is absent; cal_mc_error guarded against total-underflow NaN; breadcrumbs - stored as string arrays for numpy portability; CPU and CUDA calmarg regression gates added to CI. - - SLOW-ROTATION and FINITE-SIZE detector response (new): factored_likelihood_with_rotation provides an - FD-native slow-rotation precompute, rotation-aware lnL assembly (Path A), a delay-derivative likelihood - (Path B, --rotation-p-max), and a frequency-dependent finite-size response (Path D) with per-detector - --freqresponse-arm-length; closed-form sidereal-harmonic response; cubic time interpolation with a - precision-preserving time reference. Wired into batchmode ILE via --rotation-slow / --freqresponse, - with cupy/GPU support validated end-to-end on A100 and verify-anywhere demos in demo/rift/slowrot. - - differentiable JAX ILE (new, optional): jax_ile provides an AD-compatible extrinsic likelihood for the - rotation (Path A/B) and finite-size (Path D) likelihoods, multistart NUTS with a dense mass matrix, - gradient MAP-polish of the NUTS seeds, a phase-rotation reparameterization, evidence-weighted pooling, - posterior-ESS reporting, and a 3G sky-area-vs-SNR figure generator. An optional extra: skipped by base - CI when JAX is not installed. - - ILE extrinsic proposal controls: the extrinsic zoom box (--limit-right-ascension / --limit-declination / - --limit-inclination / --limit-psi) is now honoured by the cosine samplers, where it was silently ignored; - effective-distance reparameterization of distance<->inclination (--internal-reparam-dl-incl); SNR-scaled - extrinsic chunk size in the helper; distance slices inherit the ILE chunk size instead of a private - hardcoded 2000 and keep the pinned-d integrand on its native backend, dropping a per-block PCIe round - trip; util_RandomizeOverlapOrder interleaves ACROSS worker files, not just within them (ILE was seeing - only the first few of many workers). - - CIP posterior export: fair export by systematic resampling with a unique capped final draw - (--posterior-unique-draw), the unique-draw bound computed exactly from the scaled sum, and weight - normalization done in the input dtype before the float64 cast. - - CONVERGENCE testing and puffball: convergence_test_samples.py gains --method js_lame ('lame' on the - unbounded non-circular parameters, a boundary-reflected JS on each bounded transverse parameter, and a - lagged upper-quantile drift test over --drift-window), because the default 'lame' test is blind to slow - monotone transverse-tail drift. --js-lame-auto-threshold keys each threshold to the measured noise floor - at the DISTINCT sample count actually supplied (row-count keying is wrong once CIP pads its export with - duplicates), and --js-lame-require-lags refuses to certify convergence on an unpopulated lag window. - util_ParameterPuffball gains --append-with-random-parameter (append and SHUFFLE uniformly-random - transverse draws as a tail guard; the shuffle matters because nested ILE truncates the puffball) and - --reflect-parameter. helper_LDG_Events / util_RIFT_pseudo_pipe expose these as - --internal-test-convergence-method and the opt-in --internal-cip-transverse-tails bundle, which requires - a precessing analysis and is REJECTED rather than silently changing the spin model. Defaults unchanged. - - waveform and lalsimutils correctness: fix the spurious (l,+-m) asymmetry in hlmoft FD-mode conditioning; - zero the unpaired -fNyq bin whenever a resize truncates, not only when conditioning; centralize the - FD-grid convention choice in evaluate_fvals(lal_convention=); fix ET (E1/E2/E3) frame selection in - frame_data_to_hoft; prefer nrcatalog.compat_nrwf with a legacy fallback. New waveform symmetry test - suite (mode cross-terms, orbital-plane parity), including the IMRPhenomX-family caveats. - - workflow and submit fixes: the G-group CIP master sub used the standard CIP exe rather than --cip-exe-G - (the flat-mode no-op master is preserved); ILE honours --srate-resample-time-marginalization instead of - always doubling, and recovers the requested export rate EXACTLY rather than an integer multiple; Virgo - calibration correction convention fixed; multi-GPU ILE fan-out with a multi-container example in one ini. - - CIP eccentricity priors: ``--eccentricity-prior log_uniform`` (ingested from rift_O4c - 0.0.17.12, rapidpe-rift/rift!54) called ``np.ln``, which does not exist in numpy, so the - option raised AttributeError as soon as the prior was evaluated; its normalization was also - the uniform prior's, ``ln(ECC_MAX-ECC_MIN)``, where a density uniform in ln(e) needs - ``ln(ECC_MAX/ECC_MIN)`` (negative for the shipped 0.001/0.4 defaults). Both fixed. The - option also reached only the ``eccentricity`` coordinate, so a run sampling - ``eccentricity_squared`` -- which is what ``--use-eccentricity-squared`` asks for, and what - iteration 0 of an eccentric pseudo_pipe run uses -- silently kept the uniform-in-e^2 - density; the log-uniform prior is now installed for that coordinate too (as the same - distribution written in e^2), and the ``--ecc-min 0`` floor correction now reaches its - range. Separately, ``eccentricity_ln`` is a logarithmic coordinate under EVERY prior, so - the shipped ``--ecc-min`` default of 0.0 left a run sampling it with a ``[log(0), ...]`` - range and a prior that divided by zero; the floor correction is now keyed on the sampled - coordinate as well as on the prior, while a run that neither asks for the log-uniform - prior nor samples a log coordinate keeps ``--ecc-min`` exactly as given. Finally, - ``--eccentricity-prior`` is restricted to ``uniform``/``log_uniform`` in both CIP and - pseudo_pipe, which forwards the value verbatim: only ``log_uniform`` is branched on, so an - unsupported value ran the uniform prior while reporting the requested one. With this, the - CIP prior densities get their first test suite: test_cip_priors.py - extracts the shipped ``def`` blocks from CIP with ast rather than transcribing them, then - checks that all 39 priors evaluate finite and non-negative, that the 20 claiming a - normalized density integrate to 1 against their stated measure, and that - ``--eccentricity-prior`` selects a normalized density for every eccentricity coordinate, - including at the CLI defaults read out of CIP's own argparse calls rather than assumed. - Also fixed on rift_O4c (PR #174). - - ILE portfolio driver: a portfolio the driver cannot build now FAILS instead of silently - integrating with a different sampler. ``--sampler-method portfolio`` no longer carries a - dead ok-flag test that fell through to the plain mcsampler.MCSampler; the terminal - diagnostic and the plugin-pipeline branch no longer dereference mcsamplerPortfolio when its - import failed (that raised NameError from the diagnostic itself on a torch-free container); - an unrecognized ``--sampler-portfolio`` member and an omitted/empty member list are now - errors naming the known members. Ported from rift_O4c (PR #172). - - asimov: the RIFT bootstrap source can be named explicitly (``scheduler: bootstrap file:``), bypassing - the dependency scan, with ``{event}``/``{analysis}`` substitution and single-match globbing; the - PESummary analysis label is auto-derived and an ambiguous or raw-bilby metafile now fails loudly - instead of silently bootstrapping from whichever label sorted first. Ingested from rift_O4c 0.0.17.11 - (rapidpe-rift/rift!53). - - containers, docs, CI: container survey/warmup tooling (containers/survey_scan) with GPU-inventory - profiles and tests; container canaries fixed after setuptools 84; an upstream dependency-compatibility - check run on both GitLab and GitHub CI; new docs for distance-grid workflows, the demo catalog, the - survey_scan executable, and containers. - - test and validation infrastructure (new): an expensive pre-merge posterior SHAPE-recovery gate for the - MC integrators (test/expensive_before_merging), with per-cell budgets, a non-blocking STARVED verdict, - confirm-at-fresh-seeds before a regression blocks, an opt-in-flag probe, and a provenance guard that - refuses to measure a RIFT other than the checkout under test; a quantitative integrator benchmark - harness and a weight-clip benchmark that persists per-seed rows and provenance; regression suites for - the L0 rescue seed, the cosine-sampler limits, the AV empty-live-volume crash, the portfolio fair-draw - backend, distance-slice device residency, cip_pipeline, _rvs weight derivation, and convergence sample - order. demos/integrator_snr_lottery records the chunk-size stability and k-hat validation studies. - Measured NEGATIVE results and retractions are recorded alongside the positive ones (n_eff does not - certify correctness; k-hat does not catch confidently-wrong runs from support mismatch; the L0 'doubles - landed fraction' claim and the cap24 lnZ-bias claim are retracted). +development tree is rift_O4d; PRs refer to oshaughn/research-projects-RIT. + - (rc0) O4d base refresh: modern Python/numpy support, portable GPU execution, generic workflow + backends, hyperpipe and simulation-manager support; distance-likelihood export, parsimonious + placement preview, waveform utilities and diagnostics (PRs #129, #132, #135, #143). + - (rc1) In-loop calibration marginalization and extrinsic proposal handoff; differentiable JAX + likelihood/ILE, LISA support, EOS/coordinate extensions, multi-GPU fanout and hyperpipe improvements. + Unified time-marginalization grids change lnL relative to archived runs (PRs #139, #144, #154). + - (rc2) Portfolio/AV/GMM sampler robustness, high-SNR rescue and warm starts; evidence/error and + posterior-export fixes; slow-rotation/finite-size detector response and optional JAX sampling. + Improved convergence tests, calibration, waveform conditioning, workflows and posterior-shape + validation (PRs #155, #161, #170). + - (rc3) Adaptive time/distance and joint angular marginalization; multi-approximant support, + continuous-time posterior export, Rimsky orchestration and container integration. Fix CIP evidence + normalization, distance tails and waveform handling; strengthen calibration and CI checks + (PRs #159, #173, #178, #188). JAX flow reuse is now off by default (opt-in via --flow-reuse); + JAX --save-samples now exports fair posterior draws. 0.0.17.12 --------- diff --git a/setup.py b/setup.py index 835ab7380..13ab2686f 100644 --- a/setup.py +++ b/setup.py @@ -34,7 +34,7 @@ setuptools.setup( name="RIFT", - version="0.0.18.0rc2", # do not build on OSX machine, side effects + version="0.0.18.0rc3", # do not build on OSX machine, side effects author="Richard O'Shaughnessy", author_email="richard.oshaughnessy@ligo.org", description="RIFT parameter estimation pipeline. Note branch used is temp-RIT-Tides-port_python3_restructure_package (which will become master shortly)!",