astrogwb 0.8.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. astrogwb/__init__.py +16 -0
  2. astrogwb/background/__init__.py +39 -0
  3. astrogwb/background/analytic.py +560 -0
  4. astrogwb/background/importance/__init__.py +15 -0
  5. astrogwb/background/importance/catalog.py +119 -0
  6. astrogwb/background/importance/diagnostics.py +45 -0
  7. astrogwb/background/importance/model.py +443 -0
  8. astrogwb/background/importance/spectrum.py +440 -0
  9. astrogwb/background/simulation/__init__.py +33 -0
  10. astrogwb/background/simulation/_chunks.py +52 -0
  11. astrogwb/background/simulation/_keys.py +21 -0
  12. astrogwb/background/simulation/config.py +130 -0
  13. astrogwb/background/simulation/draw.py +753 -0
  14. astrogwb/background/simulation/ensemble.py +91 -0
  15. astrogwb/background/simulation/pool.py +73 -0
  16. astrogwb/background/snr.py +210 -0
  17. astrogwb/background/spectral.py +128 -0
  18. astrogwb/cli/__init__.py +36 -0
  19. astrogwb/cli/_common.py +20 -0
  20. astrogwb/cli/simulate.py +154 -0
  21. astrogwb/config.py +62 -0
  22. astrogwb/constants.py +65 -0
  23. astrogwb/cosmology.py +282 -0
  24. astrogwb/detector/__init__.py +77 -0
  25. astrogwb/detector/config.py +260 -0
  26. astrogwb/detector/effective_psd.py +221 -0
  27. astrogwb/detector/geometry.py +185 -0
  28. astrogwb/detector/geometry.toml +123 -0
  29. astrogwb/detector/noise_curves/AplusDesign_psd.txt +3000 -0
  30. astrogwb/detector/noise_curves/ET-000A-18_ETD_hlf_psd.txt +3000 -0
  31. astrogwb/detector/noise_curves/ET_COBA_10km_psd.txt +3000 -0
  32. astrogwb/detector/noise_curves/ET_COBA_15km_psd.txt +3000 -0
  33. astrogwb/detector/noise_curves/ET_COBA_20km_psd.txt +3000 -0
  34. astrogwb/detector/noise_curves/avirgo_O5high_NEW_psd.txt +3000 -0
  35. astrogwb/detector/noise_curves/avirgo_O5low_NEW_psd.txt +3000 -0
  36. astrogwb/detector/noise_curves/cosmic_explorer_20km_pm_strain_psd.txt +1000 -0
  37. astrogwb/detector/noise_curves/cosmic_explorer_20km_strain_psd.txt +1000 -0
  38. astrogwb/detector/noise_curves/cosmic_explorer_40km_lf_strain_psd.txt +1000 -0
  39. astrogwb/detector/noise_curves/cosmic_explorer_strain_psd.txt +1000 -0
  40. astrogwb/detector/noise_curves/kagra_128Mpc_psd.txt +1000 -0
  41. astrogwb/detector/overlap.py +553 -0
  42. astrogwb/detector/projection.py +133 -0
  43. astrogwb/detector/psd.py +46 -0
  44. astrogwb/detector/response.py +294 -0
  45. astrogwb/detector/sensitivity.py +119 -0
  46. astrogwb/detector/sensitivity.toml +52 -0
  47. astrogwb/distributions/__init__.py +21 -0
  48. astrogwb/distributions/config.py +86 -0
  49. astrogwb/distributions/interpolated.py +118 -0
  50. astrogwb/distributions/mass.py +202 -0
  51. astrogwb/distributions/orientation.py +91 -0
  52. astrogwb/distributions/redshift/__init__.py +5 -0
  53. astrogwb/distributions/redshift/base.py +190 -0
  54. astrogwb/frequency.py +238 -0
  55. astrogwb/inference/__init__.py +13 -0
  56. astrogwb/inference/gaussian.py +654 -0
  57. astrogwb/inference/grid.py +126 -0
  58. astrogwb/inference/model.py +94 -0
  59. astrogwb/populations/__init__.py +15 -0
  60. astrogwb/populations/_types.py +12 -0
  61. astrogwb/populations/coba.py +84 -0
  62. astrogwb/populations/mass/__init__.py +0 -0
  63. astrogwb/populations/mass/gaussian_mass_pair.py +32 -0
  64. astrogwb/populations/mass/uniform_mass_pair.py +33 -0
  65. astrogwb/rates.py +130 -0
  66. astrogwb/runtime.py +51 -0
  67. astrogwb/statistics/__init__.py +15 -0
  68. astrogwb/statistics/amplitude.py +103 -0
  69. astrogwb/statistics/cross_correlation.py +63 -0
  70. astrogwb/utils/__init__.py +132 -0
  71. astrogwb/utils/io.py +202 -0
  72. astrogwb/utils/numpyro.py +292 -0
  73. astrogwb/waveform/__init__.py +33 -0
  74. astrogwb/waveform/_ripple.py +427 -0
  75. astrogwb/waveform/analytical.py +335 -0
  76. astrogwb/waveform/base.py +162 -0
  77. astrogwb/waveform/factory.py +19 -0
  78. astrogwb/waveform/intensity.py +121 -0
  79. astrogwb/waveform/metadata.py +80 -0
  80. astrogwb/waveform/ripple.py +224 -0
  81. astrogwb-0.8.0.dist-info/METADATA +236 -0
  82. astrogwb-0.8.0.dist-info/RECORD +85 -0
  83. astrogwb-0.8.0.dist-info/WHEEL +4 -0
  84. astrogwb-0.8.0.dist-info/entry_points.txt +3 -0
  85. astrogwb-0.8.0.dist-info/licenses/LICENSE +21 -0
astrogwb/__init__.py ADDED
@@ -0,0 +1,16 @@
1
+ """Astrophysical stochastic gravitational-wave background utilities.
2
+
3
+ ``__version__`` is read from the installed distribution, so ``pyproject.toml``
4
+ stays its single source. It is part of every catalog's cache key: bump it
5
+ whenever a change alters what a population draw or a waveform generator
6
+ produces, or a cached catalog built by the old code keeps being served.
7
+ """
8
+
9
+ from importlib.metadata import PackageNotFoundError, version
10
+
11
+ try:
12
+ __version__ = version("astrogwb")
13
+ except PackageNotFoundError: # pragma: no cover - only in an uninstalled tree
14
+ __version__ = "0+unknown"
15
+
16
+ __all__ = ["__version__"]
@@ -0,0 +1,39 @@
1
+ from __future__ import annotations
2
+
3
+ from astrogwb.background.analytic import (
4
+ JointMassFunction,
5
+ PopulationFunction,
6
+ analytic_spectral_density,
7
+ analytic_spectral_density_from_mass_moments,
8
+ precompute_cumulative_mass_moments,
9
+ uniform_prior_mass_moments,
10
+ )
11
+ from astrogwb.background.snr import (
12
+ spectral_snr,
13
+ spectral_snr_squared,
14
+ spectral_snr_squared_per_bin,
15
+ spectral_snr_squared_per_log_frequency,
16
+ )
17
+ from astrogwb.background.spectral import (
18
+ characteristic_noise,
19
+ characteristic_strain,
20
+ omega_gw_from_spectral_density,
21
+ spectral_density_from_omega_gw,
22
+ )
23
+
24
+ __all__ = [
25
+ "JointMassFunction",
26
+ "PopulationFunction",
27
+ "analytic_spectral_density",
28
+ "analytic_spectral_density_from_mass_moments",
29
+ "characteristic_noise",
30
+ "characteristic_strain",
31
+ "omega_gw_from_spectral_density",
32
+ "precompute_cumulative_mass_moments",
33
+ "spectral_density_from_omega_gw",
34
+ "spectral_snr",
35
+ "spectral_snr_squared",
36
+ "spectral_snr_squared_per_bin",
37
+ "spectral_snr_squared_per_log_frequency",
38
+ "uniform_prior_mass_moments",
39
+ ]
@@ -0,0 +1,560 @@
1
+ r"""Analytic Newtonian-inspiral stochastic-background spectrum.
2
+
3
+ The one-sided strain spectral density of Eqs. 2, 3 and 9 of Cousins et al.,
4
+ *The Stochastic Siren* (2026), for an ordered joint source-frame component-mass
5
+ population ``p(m1, m2)``. The mass-ratio integral is evaluated on a fixed
6
+ total-mass grid and cumulatively integrated in ``M``, so the mass part is
7
+ precomputed independently of redshift and cosmology. For a uniform mass density
8
+ both integrals are elementary (``uniform_prior_mass_moments``).
9
+
10
+ The cutoff coefficient ``alpha`` is dimensionless and shares the convention of
11
+ :func:`astrogwb.waveform.termination_frequency`: a binary of source-frame total
12
+ mass ``M`` in solar masses stops contributing above the observer frequency
13
+ ``alpha / (M (1 + z) t_sun)``, with ``t_sun = G M_sun / c^3``.
14
+
15
+ All orders and grid sizes are static. Realistic strain spectra need JAX x64
16
+ mode: they underflow in float32.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import math
22
+ from collections.abc import Mapping
23
+ from typing import Protocol
24
+
25
+ import jax
26
+ import jax.numpy as jnp
27
+ from jax.typing import ArrayLike
28
+
29
+ from astrogwb.constants import (
30
+ GPC_IN_METERS,
31
+ GRAVITATIONAL_CONSTANT,
32
+ ISCO_ALPHA,
33
+ SECONDS_PER_YEAR,
34
+ SOLAR_MASS_IN_KILOGRAMS,
35
+ SOLAR_MASS_IN_SECONDS,
36
+ SPEED_OF_LIGHT,
37
+ )
38
+ from astrogwb.cosmology import hubble_constant_si, normalized_hubble_parameter
39
+ from astrogwb.utils import (
40
+ cumulative_trapezoid,
41
+ gauss_legendre_nodes_weights,
42
+ require_x64,
43
+ )
44
+
45
+ # Converts a rate density in Gpc^-3 yr^-1 and a total-mass moment in
46
+ # solar-mass^(5/3) into the SI coefficient of S_h. Combined in Python float64:
47
+ # the separate factors overflow and underflow float32.
48
+ _ASTROPHYSICAL_STRAIN_COEFFICIENT: float = (
49
+ 2.0
50
+ * (GRAVITATIONAL_CONSTANT * SOLAR_MASS_IN_KILOGRAMS) ** (5.0 / 3.0)
51
+ / (
52
+ 3.0
53
+ * math.pi ** (1.0 / 3.0)
54
+ * SPEED_OF_LIGHT**2
55
+ * GPC_IN_METERS**3
56
+ * SECONDS_PER_YEAR
57
+ )
58
+ )
59
+
60
+
61
+ class PopulationFunction(Protocol):
62
+ """Vectorized one-dimensional population callback.
63
+
64
+ Callback arguments are positional, so implementations may name their
65
+ parameters freely.
66
+ """
67
+
68
+ def __call__(
69
+ self, redshift: jax.Array, hyperparameters: Mapping[str, ArrayLike], /
70
+ ) -> jax.Array: ...
71
+
72
+
73
+ class JointMassFunction(Protocol):
74
+ """Vectorized ordered joint component-mass probability-density callback.
75
+
76
+ Callback arguments are positional, so implementations may name their
77
+ parameters freely.
78
+ """
79
+
80
+ def __call__(
81
+ self,
82
+ mass_1: jax.Array,
83
+ mass_2: jax.Array,
84
+ hyperparameters: Mapping[str, ArrayLike],
85
+ /,
86
+ ) -> jax.Array: ...
87
+
88
+
89
+ def _cumulative_mass_moment_grid(
90
+ hyperparameters: Mapping[str, ArrayLike],
91
+ joint_mass_prior_fn: JointMassFunction,
92
+ *,
93
+ minimum_component_mass: float,
94
+ maximum_component_mass: float,
95
+ mass_ratio_quadrature_order: int,
96
+ n_interp_grid: int,
97
+ ) -> tuple[jax.Array, jax.Array]:
98
+ r"""Tabulate the cumulative source-frame chirp-mass moment in total mass.
99
+
100
+ The ordered component masses are written in total mass and mass ratio,
101
+
102
+ .. math::
103
+
104
+ m_1 = \frac{M}{1+q}, \qquad m_2 = \frac{qM}{1+q}.
105
+
106
+ Multiplying :math:`\mathcal{M}^{5/3}` by the coordinate Jacobian gives the
107
+ fixed-total-mass integrand
108
+
109
+ .. math::
110
+
111
+ g(M,q;\theta) = p(m_1,m_2\mid\theta)
112
+ \frac{qM^{8/3}}{(1+q)^4}.
113
+
114
+ For component masses in :math:`[m_{\min},m_{\max}]`, the allowed mass-ratio
115
+ interval at fixed ``M`` is :math:`[q_-(M),1]`, where
116
+
117
+ .. math::
118
+
119
+ q_-(M) =
120
+ \begin{cases}
121
+ m_{\min}/(M-m_{\min}), & 2m_{\min}\le M\le m_{\min}+m_{\max},\\
122
+ M/m_{\max}-1, & m_{\min}+m_{\max}\le M\le2m_{\max}.
123
+ \end{cases}
124
+
125
+ The mass-ratio integral is evaluated first,
126
+
127
+ .. math::
128
+
129
+ H(M;\theta)=\int_{q_-(M)}^1 g(M,q;\theta)\,dq,
130
+
131
+ and sampled on a uniform total-mass grid. A cumulative trapezoid gives
132
+
133
+ .. math::
134
+
135
+ C(u;\theta)=\int_{2m_{\min}}^{
136
+ \operatorname{clip}(u,2m_{\min},2m_{\max})}H(M;\theta)\,dM.
137
+
138
+ The odd grid size places the support transition
139
+ :math:`M=m_{\min}+m_{\max}` exactly at the central node.
140
+ """
141
+ total_mass = jnp.linspace(
142
+ 2.0 * minimum_component_mass,
143
+ 2.0 * maximum_component_mass,
144
+ n_interp_grid,
145
+ dtype=jnp.float64,
146
+ )
147
+ transition = minimum_component_mass + maximum_component_mass
148
+ mass_ratio_lower = jnp.where(
149
+ total_mass <= transition,
150
+ minimum_component_mass / (total_mass - minimum_component_mass),
151
+ total_mass / maximum_component_mass - 1.0,
152
+ )
153
+
154
+ mass_ratio, mass_ratio_weights = gauss_legendre_nodes_weights(
155
+ mass_ratio_lower, 1.0, mass_ratio_quadrature_order
156
+ )
157
+
158
+ total_mass_grid = total_mass[..., None]
159
+ one_plus_mass_ratio = 1.0 + mass_ratio
160
+ mass_1 = total_mass_grid / one_plus_mass_ratio
161
+ mass_2 = total_mass_grid * mass_ratio / one_plus_mass_ratio
162
+ joint_mass_density = jnp.broadcast_to(
163
+ jnp.asarray(
164
+ joint_mass_prior_fn(mass_1, mass_2, hyperparameters),
165
+ dtype=jnp.float64,
166
+ ),
167
+ mass_ratio.shape,
168
+ )
169
+ fixed_total_mass_integrand = (
170
+ joint_mass_density
171
+ * mass_ratio
172
+ * total_mass_grid ** (8.0 / 3.0)
173
+ / one_plus_mass_ratio**4
174
+ )
175
+ mass_ratio_integral = jnp.sum(
176
+ mass_ratio_weights * fixed_total_mass_integrand,
177
+ axis=-1,
178
+ )
179
+ return total_mass, cumulative_trapezoid(mass_ratio_integral, total_mass)
180
+
181
+
182
+ def _uniform_phi(total_mass: ArrayLike, component_mass: float) -> jax.Array:
183
+ r"""Evaluate the shared total-mass antiderivative.
184
+
185
+ .. math::
186
+
187
+ \phi(M,x)=\frac{M^{11/3}}{44}-\frac{3x^2}{10}M^{5/3}
188
+ +\frac{x^3}{2}M^{2/3}.
189
+ """
190
+ total_mass = jnp.asarray(total_mass, dtype=jnp.float64)
191
+ return (
192
+ total_mass ** (11.0 / 3.0) / 44.0
193
+ - (3.0 / 10.0) * component_mass**2 * total_mass ** (5.0 / 3.0)
194
+ + 0.5 * component_mass**3 * total_mass ** (2.0 / 3.0)
195
+ )
196
+
197
+
198
+ def _uniform_cumulative_mass_moment(
199
+ total_mass: ArrayLike,
200
+ *,
201
+ minimum_component_mass: float,
202
+ maximum_component_mass: float,
203
+ ) -> jax.Array:
204
+ r"""Evaluate the exact cumulative mass moment of a uniform mass prior.
205
+
206
+ For a density that is uniform on the ordered component-mass triangle,
207
+
208
+ .. math::
209
+
210
+ p(m_1,m_2)=\frac{2}{(m_{\max}-m_{\min})^2},
211
+ \qquad m_{\min}\le m_2\le m_1\le m_{\max},
212
+
213
+ the fixed-total-mass integrand of :func:`_cumulative_mass_moment_grid`
214
+ reduces to :math:`pM^{8/3}q(1+q)^{-4}`, whose mass-ratio antiderivative is
215
+ elementary. Substituting the two branches of :math:`q_-(M)`, for which
216
+ :math:`(1+q_-)^{-1}` is :math:`1-m_{\min}/M` below the support transition
217
+ :math:`T=m_{\min}+m_{\max}` and :math:`m_{\max}/M` above it, leaves only
218
+ powers of ``M``, so the total-mass integral closes as well. Both branches
219
+ share the antiderivative :math:`\phi` of :func:`_uniform_phi`, entering as
220
+ :math:`+\phi(M,m_{\min})` below :math:`T` and :math:`-\phi(M,m_{\max})`
221
+ above it. Writing :math:`\tilde M=\operatorname{clip}(M,2m_{\min},
222
+ 2m_{\max})`,
223
+
224
+ .. math::
225
+
226
+ C(M)/p=
227
+ \begin{cases}
228
+ \phi(\tilde M,m_{\min})-\phi(2m_{\min},m_{\min}),
229
+ & \tilde M\le T,\\
230
+ \phi(T,m_{\min})-\phi(2m_{\min},m_{\min})
231
+ +\phi(T,m_{\max})-\phi(\tilde M,m_{\max}),
232
+ & \tilde M\ge T.
233
+ \end{cases}
234
+
235
+ Clipping before the branch selection keeps both branches finite, so
236
+ gradients stay free of ``NaN`` and an infinite cutoff gives the full moment.
237
+ """
238
+ lower = 2.0 * minimum_component_mass
239
+ transition = minimum_component_mass + maximum_component_mass
240
+ total_mass = jnp.asarray(total_mass, dtype=jnp.float64)
241
+ clipped = jnp.clip(total_mass, lower, 2.0 * maximum_component_mass)
242
+ origin = _uniform_phi(lower, minimum_component_mass)
243
+ below_transition = _uniform_phi(clipped, minimum_component_mass) - origin
244
+ above_transition = (
245
+ _uniform_phi(transition, minimum_component_mass)
246
+ - origin
247
+ + _uniform_phi(transition, maximum_component_mass)
248
+ - _uniform_phi(clipped, maximum_component_mass)
249
+ )
250
+ density = 2.0 / (maximum_component_mass - minimum_component_mass) ** 2
251
+ moment = density * jnp.where(
252
+ clipped <= transition, below_transition, above_transition
253
+ )
254
+ # Pin the empty integral: XLA may reassociate phi - phi into a residual.
255
+ return jnp.where(total_mass <= lower, 0.0, moment)
256
+
257
+
258
+ def _cutoff_total_mass(
259
+ alpha: ArrayLike, frequencies: jax.Array, redshift: jax.Array
260
+ ) -> jax.Array:
261
+ r"""Source-frame total mass in solar masses at the inspiral cutoff.
262
+
263
+ Inverts :math:`f = \alpha / ((1 + z) M t_\odot)` for the source-frame
264
+ total mass, with :math:`t_\odot` =
265
+ :data:`~astrogwb.constants.SOLAR_MASS_IN_SECONDS` converting the
266
+ dimensionless :math:`\alpha` of
267
+ :func:`astrogwb.waveform.termination_frequency` into solar masses.
268
+ Returns shape ``(frequency, redshift_node)``.
269
+ """
270
+ return alpha / (
271
+ frequencies[:, None] * (1.0 + redshift[None, :]) * SOLAR_MASS_IN_SECONDS
272
+ )
273
+
274
+
275
+ @require_x64
276
+ def uniform_prior_mass_moments(
277
+ frequencies: jax.Array,
278
+ *,
279
+ minimum_redshift: float,
280
+ maximum_redshift: float,
281
+ minimum_component_mass: float,
282
+ maximum_component_mass: float,
283
+ alpha: float = ISCO_ALPHA,
284
+ redshift_quadrature_order: int = 64,
285
+ ) -> jax.Array:
286
+ r"""Evaluate exact mass moments for a uniform component-mass prior.
287
+
288
+ This is the closed-form counterpart of
289
+ :func:`precompute_cumulative_mass_moments` for a density that is uniform on
290
+ the ordered component-mass triangle. Both the mass-ratio and the total-mass
291
+ integrals are elementary there, so the cumulative moment is evaluated
292
+ directly at every cutoff,
293
+
294
+ .. math::
295
+
296
+ U_{fa}=\frac{\alpha}{f_f(1+z_a)\,t_\odot}, \qquad M_{fa}=C(U_{fa}),
297
+
298
+ where :math:`t_\odot=GM_\odot/c^3`. Exact to round-off. Pass the same
299
+ ``redshift_quadrature_order`` to
300
+ :func:`analytic_spectral_density_from_mass_moments`.
301
+
302
+ Parameters
303
+ ----------
304
+ frequencies
305
+ One-dimensional observer-frame frequency array in Hz. Values must be
306
+ finite and strictly positive.
307
+ minimum_redshift, maximum_redshift
308
+ Redshift integration bounds.
309
+ minimum_component_mass, maximum_component_mass
310
+ Shared source-frame component-mass bounds in solar masses. They also fix
311
+ the normalized density ``2 / (maximum_component_mass - minimum_component_mass)**2``.
312
+ alpha
313
+ Dimensionless source-frame cutoff coefficient, defining
314
+ ``f_max = alpha / (M * SOLAR_MASS_IN_SECONDS)`` in Hz for a
315
+ source-frame total mass ``M`` in solar masses. Shares the convention
316
+ of :func:`astrogwb.waveform.termination_frequency`. Use ``inf`` for
317
+ no cutoff.
318
+ redshift_quadrature_order
319
+ Gauss-Legendre order of the redshift nodes.
320
+
321
+ Returns
322
+ -------
323
+ jax.Array
324
+ Cumulative mass moments of shape ``(frequency, redshift_node)``. Values
325
+ are exactly zero where the cutoff falls below ``2 * minimum_component_mass``
326
+ and exactly the full mass moment where it lies above
327
+ ``2 * maximum_component_mass``.
328
+ """
329
+ frequencies = jnp.asarray(frequencies, dtype=jnp.float64)
330
+ redshift, _ = gauss_legendre_nodes_weights(
331
+ minimum_redshift, maximum_redshift, redshift_quadrature_order
332
+ )
333
+ total_mass_upper = _cutoff_total_mass(alpha, frequencies, redshift)
334
+ return _uniform_cumulative_mass_moment(
335
+ total_mass_upper,
336
+ minimum_component_mass=minimum_component_mass,
337
+ maximum_component_mass=maximum_component_mass,
338
+ )
339
+
340
+
341
+ @require_x64
342
+ def precompute_cumulative_mass_moments(
343
+ frequencies: jax.Array,
344
+ hyperparameters: Mapping[str, ArrayLike],
345
+ joint_mass_prior_fn: JointMassFunction,
346
+ *,
347
+ minimum_redshift: float,
348
+ maximum_redshift: float,
349
+ minimum_component_mass: float,
350
+ maximum_component_mass: float,
351
+ alpha: float = ISCO_ALPHA,
352
+ mass_ratio_quadrature_order: int = 64,
353
+ n_interp_grid: int = 2049,
354
+ redshift_quadrature_order: int = 64,
355
+ ) -> jax.Array:
356
+ r"""Evaluate fixed mass moments at every frequency-redshift cutoff.
357
+
358
+ For redshift quadrature nodes :math:`z_a`, this function constructs
359
+
360
+ .. math::
361
+
362
+ U_{fa}=\frac{\alpha}{f_f(1+z_a)\,t_\odot}, \qquad M_{fa}=C(U_{fa}),
363
+
364
+ with :math:`t_\odot=GM_\odot/c^3` converting the dimensionless
365
+ :math:`\alpha` into a total mass in solar masses, and linearly
366
+ interpolates :math:`C(U_{fa})` from a uniform total-mass grid.
367
+ The result has shape ``(frequency, redshift_node)`` and can be reused while
368
+ sampling cosmology or the redshift distribution with a fixed mass
369
+ population. Values below the physical total-mass support are exactly zero;
370
+ values above it are exactly the full mass moment.
371
+
372
+ Parameters
373
+ ----------
374
+ frequencies
375
+ Frequency grid in Hz.
376
+ hyperparameters
377
+ Population hyperparameters.
378
+ joint_mass_prior_fn
379
+ Joint component-mass density function.
380
+ minimum_redshift
381
+ Lower redshift bound.
382
+ maximum_redshift
383
+ Upper redshift bound.
384
+ minimum_component_mass
385
+ Lower component-mass bound.
386
+ maximum_component_mass
387
+ Upper component-mass bound.
388
+ alpha
389
+ Inspiral power-law exponent.
390
+ mass_ratio_quadrature_order
391
+ Mass-ratio quadrature order.
392
+ n_interp_grid
393
+ Number of interpolation grid nodes.
394
+ redshift_quadrature_order
395
+ Redshift quadrature order.
396
+ """
397
+ frequencies = jnp.asarray(frequencies, dtype=jnp.float64)
398
+ redshift, _ = gauss_legendre_nodes_weights(
399
+ minimum_redshift, maximum_redshift, redshift_quadrature_order
400
+ )
401
+ total_mass_upper = _cutoff_total_mass(alpha, frequencies, redshift)
402
+ total_mass, cumulative_mass_moment = _cumulative_mass_moment_grid(
403
+ hyperparameters,
404
+ joint_mass_prior_fn,
405
+ minimum_component_mass=minimum_component_mass,
406
+ maximum_component_mass=maximum_component_mass,
407
+ mass_ratio_quadrature_order=mass_ratio_quadrature_order,
408
+ n_interp_grid=n_interp_grid,
409
+ )
410
+ return jnp.interp(total_mass_upper, total_mass, cumulative_mass_moment)
411
+
412
+
413
+ @require_x64
414
+ def analytic_spectral_density_from_mass_moments(
415
+ frequencies: jax.Array,
416
+ hyperparameters: Mapping[str, ArrayLike],
417
+ merger_rate_fn: PopulationFunction,
418
+ cumulative_mass_moments: jax.Array,
419
+ *,
420
+ minimum_redshift: float,
421
+ maximum_redshift: float,
422
+ redshift_quadrature_order: int = 64,
423
+ ) -> jax.Array:
424
+ r"""Evaluate the strain PSD from fixed cumulative mass moments.
425
+
426
+ ``cumulative_mass_moments[f, a]`` must have been prepared at the same
427
+ frequency ``f`` and redshift quadrature node ``z_a`` used here. The spectrum
428
+ is the matrix-vector contraction
429
+
430
+ .. math::
431
+
432
+ S_h(f_f;\theta)=\frac{C_{\rm astro}}{H_0} f_f^{-7/3}
433
+ \sum_a w_a\frac{R(z_a;\theta)}
434
+ {E(z_a;\Omega_m)(1+z_a)^{4/3}}M_{fa}.
435
+
436
+ A fixed ``(F, Z)`` array can be reused throughout an MCMC over cosmology or
437
+ the redshift distribution.
438
+
439
+ Parameters
440
+ ----------
441
+ frequencies
442
+ Frequency grid in Hz.
443
+ hyperparameters
444
+ Population hyperparameters.
445
+ merger_rate_fn
446
+ Source-frame merger-rate function.
447
+ cumulative_mass_moments
448
+ Precomputed cumulative mass moments.
449
+ minimum_redshift
450
+ Lower redshift bound.
451
+ maximum_redshift
452
+ Upper redshift bound.
453
+ redshift_quadrature_order
454
+ Redshift quadrature order.
455
+ """
456
+ frequencies = jnp.asarray(frequencies, dtype=jnp.float64)
457
+ cumulative_mass_moments = jnp.asarray(cumulative_mass_moments, dtype=jnp.float64)
458
+ redshift, redshift_weights = gauss_legendre_nodes_weights(
459
+ minimum_redshift, maximum_redshift, redshift_quadrature_order
460
+ )
461
+ merger_rate = jnp.broadcast_to(
462
+ jnp.asarray(merger_rate_fn(redshift, hyperparameters), dtype=jnp.float64),
463
+ redshift.shape,
464
+ )
465
+ expansion = normalized_hubble_parameter(
466
+ redshift, jnp.asarray(hyperparameters["Omega_m"], dtype=jnp.float64)
467
+ )
468
+ redshift_integrand = merger_rate / (expansion * (1.0 + redshift) ** (4.0 / 3.0))
469
+ redshift_mass_moments = cumulative_mass_moments @ (
470
+ redshift_weights * redshift_integrand
471
+ )
472
+
473
+ coefficient = _ASTROPHYSICAL_STRAIN_COEFFICIENT / hubble_constant_si(
474
+ jnp.asarray(hyperparameters["H0"], dtype=jnp.float64)
475
+ )
476
+ return coefficient * frequencies ** (-7.0 / 3.0) * redshift_mass_moments
477
+
478
+
479
+ @require_x64
480
+ def analytic_spectral_density(
481
+ frequencies: jax.Array,
482
+ hyperparameters: Mapping[str, ArrayLike],
483
+ merger_rate_fn: PopulationFunction,
484
+ joint_mass_prior_fn: JointMassFunction,
485
+ *,
486
+ minimum_redshift: float,
487
+ maximum_redshift: float,
488
+ minimum_component_mass: float,
489
+ maximum_component_mass: float,
490
+ alpha: float = ISCO_ALPHA,
491
+ quadrature_order: int = 64,
492
+ n_interp_grid: int = 2049,
493
+ ) -> jax.Array:
494
+ r"""Evaluate the analytic inspiral-only one-sided strain PSD ``S_h(f)``.
495
+
496
+ This convenience API performs both stages in one call: it tabulates the
497
+ cumulative mass moment, interpolates it at the frequency-redshift cutoffs,
498
+ and contracts those fixed mass moments with the redshift-dependent merger
499
+ rate and cosmology. When the mass population is fixed during MCMC, use
500
+ :func:`precompute_cumulative_mass_moments` and
501
+ :func:`analytic_spectral_density_from_mass_moments` separately instead.
502
+
503
+ Parameters
504
+ ----------
505
+ frequencies
506
+ One-dimensional observer-frame frequency array in Hz. Values must be
507
+ finite and strictly positive.
508
+ hyperparameters
509
+ Population/cosmology parameters supplied unchanged to every callback.
510
+ ``H0`` (km s^-1 Mpc^-1) and ``Omega_m`` are required.
511
+ merger_rate_fn
512
+ ``fn(redshift, hyperparameters)`` returning the absolute source-frame
513
+ merger-rate density in Gpc^-3 yr^-1.
514
+ joint_mass_prior_fn
515
+ ``fn(mass_1, mass_2, hyperparameters)`` returning a normalized ordered
516
+ density with respect to ``dmass_1 dmass_2``.
517
+ minimum_redshift, maximum_redshift
518
+ Redshift integration bounds.
519
+ minimum_component_mass, maximum_component_mass
520
+ Shared source-frame component-mass bounds in solar masses.
521
+ alpha
522
+ Dimensionless source-frame cutoff coefficient, defining
523
+ ``f_max = alpha / (M * SOLAR_MASS_IN_SECONDS)`` in Hz for a
524
+ source-frame total mass ``M`` in solar masses. Shares the convention
525
+ of :func:`astrogwb.waveform.termination_frequency`. Use ``inf`` for
526
+ no cutoff.
527
+ quadrature_order
528
+ Shared Gauss-Legendre order for redshift and mass ratio.
529
+ n_interp_grid
530
+ Odd number of uniform total-mass interpolation nodes. The default gives
531
+ 2048 intervals; use 1025, 2049, and 4097 for grid-refinement checks.
532
+
533
+ Returns
534
+ -------
535
+ jax.Array
536
+ One-sided strain spectral density in Hz^-1, with the same shape as
537
+ ``frequencies``.
538
+ """
539
+ cumulative_mass_moments = precompute_cumulative_mass_moments(
540
+ frequencies,
541
+ hyperparameters,
542
+ joint_mass_prior_fn,
543
+ minimum_redshift=minimum_redshift,
544
+ maximum_redshift=maximum_redshift,
545
+ minimum_component_mass=minimum_component_mass,
546
+ maximum_component_mass=maximum_component_mass,
547
+ alpha=alpha,
548
+ mass_ratio_quadrature_order=quadrature_order,
549
+ n_interp_grid=n_interp_grid,
550
+ redshift_quadrature_order=quadrature_order,
551
+ )
552
+ return analytic_spectral_density_from_mass_moments(
553
+ frequencies,
554
+ hyperparameters,
555
+ merger_rate_fn,
556
+ cumulative_mass_moments,
557
+ minimum_redshift=minimum_redshift,
558
+ maximum_redshift=maximum_redshift,
559
+ redshift_quadrature_order=quadrature_order,
560
+ )
@@ -0,0 +1,15 @@
1
+ """Importance weighting of a fixed reference catalog against a target population.
2
+
3
+ The package is split into four submodules, imported directly:
4
+
5
+ - :mod:`astrogwb.background.importance.catalog` holds the importance proposal: fixed-size
6
+ reference draws of a population and their per-source intensity.
7
+ - :mod:`astrogwb.background.importance.spectrum` holds the estimator: the background
8
+ spectrum as a redshift quadrature over the reweighted intrinsic draws.
9
+ - :mod:`astrogwb.background.importance.model` holds :class:`~astrogwb.background.importance.model.CatalogModel`,
10
+ the catalog as a :class:`~astrogwb.inference.model.SpectralDensityModel`.
11
+ - :mod:`astrogwb.background.importance.diagnostics` holds the effective-sample-size
12
+ diagnostics of the weights and the amplitude cumulants of a catalog.
13
+ """
14
+
15
+ __all__: list[str] = []