debrispy.kernel

Functions

compute_phi_row_gauss(i, a_val, r_grid, psi_func)	Compute Phi(r,a) for a general eccentricity distribution Psi(e,a) Piecewise, fixed-order Gauss-Legendre integration for a single row of the Phi(r,a) kernel.
compute_phi_row_gauss_adaptive(i, a_val, ...)	Adaptive Gauss-Legendre integration for one row of Phi(r,a).
compute_phi_row_quad(i, a_val, r_grid, psi_func)	Compute Phi(r,a) for an entire row using scipy.integrate.quad.
compute_phi_row_trapz(i, a_val, r_grid, ...)	Compute Phi(r,a) for a general eccentricity distribution Psi(e,a) This method is used to compute a single row of Phi(r,a) for a given a_val using the trapezium rule.
compute_phi_single_gauss(pt, n_points, eps, ...)	Compute Phi(r,a) for a single point using fixed-order Gauss-Legendre quadrature with piecewise integration.
compute_phi_single_gauss_adaptive(pt, ...[, ...])	Compute Phi(r,a) for a single point using adaptive Gauss-Legendre quadrature.
compute_phi_single_quad(pt, eps, psi_func, ...)	Compute Phi(r,a) for a single point using scipy.integrate.quad.

Classes

Kernel(eccentricity_profile, r_min, r_max[, ...])

Kernel class for easy conversion of a defined eccentrcity profile into the eccentricity kernel required for calculating the ASD.

class debrispy.kernel.Kernel(eccentricity_profile: EccentricityProfile, r_min: float, r_max: float, num_a_points: int = 500, num_r_points: int = 500)

Bases: object

Kernel class for easy conversion of a defined eccentrcity profile into the eccentricity kernel required for calculating the ASD.

compute(eps: float = 1e-08, tol: float = 1e-10, method: str = 'gauss', rayleigh_approx: bool = False, adaptive_grid: bool = False, upper_limit: float | Callable | None = None, interpolation_method: str = 'linear', adaptive_integration: bool = False, split_points: list | None = None, n_points: int = 64, max_level: int = 25, n_jobs: int = 4) → None

Compute the kernel for the eccentricity distribution

Parameters:

• eps (float) – Epsilon precision parameter for the integration.

• tol (float) – Tolerance parameter for the integration.

• method (str) – Integration method to use. Options: ‘gauss’ (Gauss-Legendre Quadrature), ‘trapz’ (NumPy Trapezium), ‘quad’ (SciPy Quad Library)

• rayleigh_approx (bool) – Whether to use the Rayleigh approximation for the integration. (Only used for RayleighEccentricity)

• adaptive_grid (bool) – For Gauss-Legendre Quadrature: Whether to use an adaptive grid for the integration.

• upper_limit (float or callable) – Upper limit for the integration.

• interpolation_method (str) – Interpolation method to use. Options: ‘linear’ (linear interpolation), ‘cubic’ (cubic interpolation), ‘nearest’ (nearest neighbor interpolation)

• adaptive_integration (bool) – For Gauss-Legendre Quadrature: Whether to use an adaptive integration for the integration.

• split_points (list) – For Gauss-Legendre Quadrature: List of split points for the integration.

• n_points (int) – For Gauss-Legendre Quadrature: Number of points for the integration.

• max_level (int) – For Gauss-Legendre Quadrature: Maximum level for the integration.

• n_jobs (int) – Number of jobs to run in parallel.

Raises:

ValueError – If the integration method is not valid.:

compute_grad() → None

Compute the gradient of Phi(r,a) for a unique eccentricity distribution e = e(a), for the initialised grid. Uses the chain rule to compute the gradient.

get_values(a_vals, r_vals) → ndarray

num_adaptive_points() → int

Return the number of points in the adaptive Phi mesh.

phi_grid() → ndarray

Returns phi_grid if it has been computed.

phi_samples() → ndarray

Returns phi_samples if it has been computed.

plot(cmap: str = 'viridis', vmin: float | None = None, vmax: float | None = None, a_lim: tuple | None = None, r_lim: tuple | None = None, save: bool = False, filename: str | None = None, shading: str = 'auto', show_edges: bool = True, edgecolor: str = 'k', linewidth: float = 0.2, points: bool = False, point_size: float = 10) → None

Main plotting function for the Kernel.

This function plots the Phi(r,a) grid, or the Phi(r,a) samples, based on the chosen grid values.

Parameters:

• cmap (str) – The colormap to use.

• vmin (float) – The minimum value of the colormap.

• vmax (float) – The maximum value of the colormap.

• a_lim (tuple) – The limits of the semi-major axis.

• r_lim (tuple) – The limits of the radius.

• save (bool) – Whether to save the plot.

• filename (str) – The filename to save the plot to.

• shading (str) – The shading to use.

• show_edges (bool) – Whether to show the edges when using triangulation (unstructured grid).

• edgecolor (str) – The color of the edges (unstructured grid)

• linewidth (float) – The width of the edge (unstructured grid)

• points (bool) – Whether to plot a scatter plot instead of a color mesh.

• point_size (float) – The size of the points in the scatter plot.

plot_grad(type: str = 'norm', vmin: float | None = None, vmax: float | None = None, a_lim: tuple | None = None, r_lim: tuple | None = None, cmap: str = 'viridis', save: bool = False, filename: str | None = None) → None

Plot the gradient of the kernel.

Parameters:

• type (str) – The type of gradient to plot (‘norm’, ‘da’, ‘dr’, or ‘all’).

• vmin (float) – The minimum value of the gradient to plot.

• vmax (float) – The maximum value of the gradient to plot.

• a_lim (tuple) – The limits of the a-axis.

• r_lim (tuple) – The limits of the r-axis.

• cmap (str) – The colormap to use.

• save (bool) – Whether to save the plot.

• filename (str) – The filename to save the plot to.

plot_phi_kappa(cmap: str = 'viridis', save: bool = False, filename: str | None = None, a_slice: float | None = None) → None

Helper function to plot Phi(kappa, a) using sorted kappa and a 2D color plot, plus an optional secondary 1D plot of Phi(kappa) at a given a_slice (default: middle of a_grid).

Parameters:

• cmap (str) – The colormap to use.

• save (bool) – Whether to save the plot.

• filename (str) – Filename to save to (required if save=True).

• a_slice (float) – The a-value to slice at (default: middle of a_grid).

plot_slice(fix_a: float | None = None, fix_r: float | None = None, log_y: bool = False, log_x: bool = False, save: bool = False, filename: str | None = None, x_lim: tuple | None = None, y_lim: tuple | None = None) → None

Plot a 1D marginal slice of Phi(r, a) at fixed a or fixed r.

Parameters:

• fix_a (float) – Value of a at which to fix and vary r.

• fix_r (float) – Value of r at which to fix and vary a.

• log_y (bool) – Whether to plot the y-axis on a logarithmic scale.

• log_x (bool) – Whether to plot the x-axis on a logarithmic scale.

• save (bool) – Whether to save the plot.

• filename (str) – Filename to save to (required if save=True).

• x_lim (tuple) – Limits of the x-axis.

• y_lim (tuple) – Limits of the y-axis.

debrispy.kernel.compute_phi_row_gauss(i: int, a_val: float, r_grid: ndarray, psi_func: Callable, n_points: int = 64, eps: float = 1e-08, upper_limit: float | Callable | None = None, split_points: list[float | Callable] | None = None)

Compute Phi(r,a) for a general eccentricity distribution Psi(e,a) Piecewise, fixed-order Gauss-Legendre integration for a single row of the Phi(r,a) kernel.

Parameters:

• i (int) – Row index corresponding to a_val.

• a_val (float) – Semi-major axis value at this row.

• r_grid (np.ndarray) – Grid of radius values r.

• psi_func (Callable) – Function ψ(e, a) returning the eccentricity distribution.

• n_points (int) – Number of Gauss-Legendre quadrature points.

• eps (float) – Small epsilon to avoid sqrt singularities.

• upper_limit (float or callable (optional)) – Function of a (i.e., lambda a: … ) returning the upper limit of integration. If None, uses fixed upper limit of 1.0.

• split_points (list of float or callables, optional) – Breakpoints for piecewise integration. Each element may be a number or a function of a_val; only those strictly between e_min and e_max are used, in ascending order.

Returns:

• i (int) – The same row index passed in.

• phi_row (ndarray) – The computed Φ values for this a_val across r_grid.

debrispy.kernel.compute_phi_row_gauss_adaptive(i, a_val, r_grid, psi_func, n_points=64, eps=1e-08, upper_limit=None, tol=1e-10, max_level=25)

Adaptive Gauss-Legendre integration for one row of Phi(r,a).

This is particularly useful when there are discontinuities in the eccentricity distribution, but the user does not know where they exactly are (i.e. cannot provide split points).

Recursively splits [e_min,e_max] until the relative error tolerance is met or the maximum recursion depth is reached.

Parameters:

• i (int) – row index

• a_val (float) – semi-major axis

• r_grid (array_like) – radii to evaluate

• psi_func (callable) – psi(e,a) → eccentricity distribution

• n_points (int) – base number of Gauss-Legendre quadrature points

• eps (float) – small offset from kappa to avoid singularity

• upper_limit (None or callable) – if callable, upper_limit(a_val) → e_max; else e_max=1

• tol (float) – relative error tolerance (Default is 1e-10)

• max_level (int) – recursion depth limit (Default is 25)

Returns:

• i (int) – row index

• phi_row (np.ndarray) – computed Phi(r,a) values for this row

debrispy.kernel.compute_phi_row_quad(i: int, a_val: float, r_grid: ndarray, psi_func: Callable, eps: float = 1e-08, upper_limit: Callable | None = None)

Compute Phi(r,a) for an entire row using scipy.integrate.quad.

Parameters:

• i (int) – The index of the a_val in the a_grid.

• a_val (float) – The value of a to compute Phi(r,a) for (row)

• r_grid (np.ndarray) – The r_grid to compute Phi(r,a) for.

• psi_func (callable) – psi(e, a) → eccentricity distribution. The first argument is eccentricity (float), the second is semi-major axis (float).

• eps (float) – Small epsilon to avoid sqrt singularities.

• upper_limit (callable or None) – Function of a (i.e., lambda a: …) returning the upper limit of integration. If None, uses fixed upper limit of 1.0.

Returns:

phi_row – The computed Phi(r, a) values for the entire row.

Return type:

np.ndarray

debrispy.kernel.compute_phi_row_trapz(i: int, a_val: float, r_grid: ndarray, e_grid: ndarray, psi_col: ndarray, eps: float = 1e-05) → Tuple[int, ndarray]

Compute Phi(r,a) for a general eccentricity distribution Psi(e,a) This method is used to compute a single row of Phi(r,a) for a given a_val using the trapezium rule.

Parameters:

iint

The index of the a_val in the a_grid.

a_valfloat

The value of a to compute Phi(r,a) for (row)

r_gridnp.ndarray

The r_grid to compute Phi(r,a) for.

e_gridnp.ndarray

The eccentricity grid to compute Phi(r,a) from (integrate over).

psi_colnp.ndarray

The eccentricity distribution Psi(e,a) to compute Phi(r,a) from.

epsfloat

Epsilon precision parameter for the integration. (Default is 1e-5, lower is more accurate but can lead to aliasing/numerical instability when using the trapezium rule)

debrispy.kernel.compute_phi_single_gauss(pt: tuple, n_points: int, eps: float, psi_func: Callable, upper_limit: Callable | None, split_points: list[float | Callable] | None)

Compute Phi(r,a) for a single point using fixed-order Gauss-Legendre quadrature with piecewise integration. This is used for fixed-order Gauss-Legendre integration as part of the adaptive grid method.

Parameters:

• pt (tuple) – (a, r)

• n_points (int) – Number of Gauss-Legendre quadrature points per subinterval.

• eps (float) – Small epsilon to avoid sqrt singularities and overlapping bounds.

• psi_func (callable) – psi(e,a) → eccentricity distribution

• upper_limit (None or callable) – if callable, upper_limit(a) → e_max; else e_max=1

• split_points (list of float or callables, optional) – Breakpoints for piecewise integration. Each element may be a number or a function of a_val; only those strictly between e_min and e_max are used, in ascending order.

debrispy.kernel.compute_phi_single_gauss_adaptive(pt: tuple, n_points: int, eps: float, psi_func: Callable, upper_limit: float | Callable | None, tol: float = 1e-10, max_level: int = 25)

Compute Phi(r,a) for a single point using adaptive Gauss-Legendre quadrature. This is used for adaptive integration when using the adaptive grid method.

Parameters:

• pt (tuple) – (a, r)

• n_points (int) – Base number of Gauss-Legendre quadrature points.

• eps (float) – Small epsilon to avoid sqrt singularities.

• psi_func (callable) – psi(e,a) → eccentricity distribution

• upper_limit (None or callable) – if callable, upper_limit(a) → e_max; else e_max=1

• tol (float) – Relative error tolerance (Default is 1e-10).

• max_level (int) – Recursion depth limit (Default is 25).

debrispy.kernel.compute_phi_single_quad(pt: Tuple[float, float], eps: float, psi_func: Callable, upper_limit: Callable | None) → float

Compute Phi(r,a) for a single point using scipy.integrate.quad.

Parameters:

• pt (tuple) – (a, r)

• eps (float) – Small epsilon to avoid sqrt singularities.

• psi_func (callable) – psi(e, a) → eccentricity distribution. The first argument is eccentricity (float), the second is semi-major axis (float).

• upper_limit (callable or None) – Function of a (i.e., lambda a: …) returning the upper limit of integration. If None, uses fixed upper limit of 1.0.

Returns:

phi_val – The computed Phi(r, a) value.

Return type:

float