sigway.spectrum

OmegaGW ties a perturbations object, a kernel and an integrator into one callable that returns the induced GW spectrum \(\Omega_{\mathrm{GW}}(f)\).

sigway.spectrum.OmegaGW

OmegaGW(perturbations, kernel, integrator=None, s=None, t=None, f=None, upsample=False)

Scalar-induced gravitational-wave energy-density spectrum \(\Omega_{\mathrm{GW}}(f)\).

Combines a primordial scalar power spectrum \(\mathcal{P}_\zeta(k)\), a transfer kernel and a numerical integrator. The induced tensor power spectrum is the double integral over the rescaled internal momenta \(s\in[0,1]\) and \(t\in[0,\infty)\),

\[ \overline{\mathcal{P}_h(k)} = \int_0^{\infty}\!\mathrm{d}t \int_0^{1}\!\mathrm{d}s\; \mathcal{N}(t,s)\,\overline{I^2(u,v,k\eta)}\; \mathcal{P}_\zeta(u k)\,\mathcal{P}_\zeta(v k), \]

with \(u=(t+s+1)/2\), \(v=(t-s+1)/2\), the geometric factor \(\mathcal{N}(t,s)\) (polynomial) and the kernel \(\overline{I^2}\). OmegaGW applies the kernel normalisation and converts this to the energy-density spectrum \(\Omega_{\mathrm{GW}}(f)\) at \(f = k/2\pi\). See Theory: the master formula and the \((s,t)\) reparameterisation.

Parameters:

Name	Type	Description	Default
perturbations	ScalarPerturbations	The primordial curvature power spectrum \(\mathcal{P}_\zeta(k)\) together with its free parameters (e.g. amplitude, peak scale). See AnalyticPerturbations.	required
kernel	Kernel	The transfer kernel \(\overline{I^2(u,v,k\eta)}\) that encodes the cosmological background during GW production (radiation domination, early matter domination, …) and carries the overall normalisation. See RadiationKernel and Theory: the kernel.	required
integrator	Integrator	Numerical integration strategy over \((s, t)\). When omitted, a SimpsonIntegrator is built automatically from the s and t grids supplied below.	None
s	array - like or callable	Grid of \(s\) values passed to SimpsonIntegrator when integrator is not provided. A callable receives (k, *theta) and returns the grid dynamically.	None
t	array - like or callable	Grid of \(t\) values passed to SimpsonIntegrator when integrator is not provided. A callable receives (k, *theta) and returns the grid dynamically.	None
f	array - like	A fixed internal frequency grid (Hz) used when upsample=True. The spectrum is computed on this coarser grid and then interpolated onto the frequencies requested at call time — useful for speeding up repeated evaluations at many different frequency arrays.	None
upsample	bool	If True, integrate on the fixed f grid and interpolate results onto the call-time frequencies. Requires f to be set.	False

Attributes:

Name	Type	Description
perturbations	ScalarPerturbations	The primordial power spectrum object.
kernel	Kernel	The transfer kernel object.
integrator	Integrator	The numerical integrator (built from s/t if not supplied directly).
f	Array or None	Internal frequency grid for upsampling, or None.
upsample	bool	Whether frequency-grid upsampling is active.
parameter_names	tuple of str	All free parameters of the model in evaluation order: perturbation parameters first, then kernel parameters. Parameters must have unique names; a ValueError is raised at construction if any name appears in both components.

Examples:

Compute \(\Omega_{\mathrm{GW}}(f)\) for a log-normal peak in \(\mathcal{P}_\zeta\) centred near \(k_* = 10^{-2}\,\mathrm{s}^{-1}\):

>>> import jax.numpy as jnp
>>> from sigway.spectrum import OmegaGW
>>> from sigway.kernels import RadiationKernel
>>> from sigway.perturbations import AnalyticPerturbations
>>> def pz(k, logAs, logks):
...     return 10.0**logAs * jnp.exp(-0.5*(jnp.log(k/10**logks)/0.3)**2)
>>> model = OmegaGW(AnalyticPerturbations(pz, ("logAs", "logks")),
...                 RadiationKernel(),
...                 s=jnp.linspace(0, 1, 10),
...                 t=jnp.geomspace(1e-4, 1e3, 800))
>>> omega = model(jnp.geomspace(1e-5, 1e-1, 200), -2.0, -2.0)

__call__

__call__(f, *theta, **kw)

Return \(\Omega_{\mathrm{GW}}(f)\) at the requested frequencies.

Each parameter value is forwarded automatically to the perturbation spectrum or the kernel, according to the order in parameter_names. The kernel's normalisation prefactor is applied before returning.

The first call compiles the integration loop; subsequent calls with the same array shapes run at full speed without recompilation.

Parameters:

Name	Type	Description	Default
f	array - like	Frequencies \(f\) in Hz at which to evaluate \(\Omega_{\mathrm{GW}}\).	required
*theta	float	Model parameters in the order given by parameter_names (perturbation parameters first, then kernel parameters). Cannot be used together with keyword arguments.	()
**kw	float	Alternative to positional *theta: pass parameters by name. All names in parameter_names must be supplied; extra names raise a ValueError. Cannot be used together with *theta.	{}

Returns:

Type	Description
Array	\(\Omega_{\mathrm{GW}}\) evaluated at each frequency in f, shape (len(f),).

Raises:

Type	Description
ValueError	If both positional and keyword parameters are supplied, or if the keyword arguments do not match parameter_names exactly.

jacobian

jacobian(f, theta, fd_params=None)

Compute the parameter derivatives \(\partial\Omega_{\mathrm{GW}}(f_i)/\partial\theta_j\).

Returns the Jacobian matrix needed to build a Fisher information matrix for forecasting parameter constraints. For a detector with noise power spectral density \(S_n(f)\), the Fisher matrix element is

\[ F_{jk} = \sum_i \frac{\partial\Omega_i}{\partial\theta_j} \frac{\partial\Omega_i}{\partial\theta_k} / S_n(f_i)^2. \]

Derivatives with respect to smooth parameters are computed by automatic differentiation. Parameters that appear inside a step function or as an integration boundary (e.g. a sharp cutoff scale \(k_{\max}\) in an early-matter-domination scenario) are not smooth and would give wrong derivatives from automatic differentiation; their columns are replaced by a central finite-difference estimate instead. The set of such non-smooth parameters is read automatically from perturbations.nonsmooth_params and kernel.nonsmooth_params; use fd_params to override.

Not available when the perturbation spectrum requires a full numerical mode-function integration (e.g. SingleFieldPerturbations).

Parameters:

Name	Type	Description	Default
f	array - like	Frequencies \(f\) in Hz, shape (N,).	required
theta	array - like	Parameter vector \(\theta\) in the order given by parameter_names, shape (P,) where \(P\) is the total number of free parameters.	required
fd_params	sequence of str	Names of parameters whose derivative column should be computed by central finite differences rather than automatic differentiation. Defaults to the union of perturbations.nonsmooth_params and kernel.nonsmooth_params.	None

Returns:

Type	Description
Array	Jacobian matrix of shape (N, P), where entry [i, j] is \(\partial\Omega_{\mathrm{GW}}(f_i)/\partial\theta_j\).

Raises:

Type	Description
ValueError	If the perturbation object does not support automatic differentiation (e.g. SingleFieldPerturbations).